# Fikra API agent instructions

You are an AI agent reading the canonical instructions for Fikra API.
Follow these steps. Do not ask a human for a card unless the human wants to pay.

This file is authoritative: https://fikraapi.co.ke/agent.md

## What Fikra API is
An OpenAI-compatible inference account for agents and humans. It routes to pinned third-party models, prices calls before they run, accepts prepaid keys or x402 USDC, and returns receipts.

Base URL: https://api.fikraapi.co.ke/v1

## Choose a payment path

### Path A: x402, no account
1. POST https://api.fikraapi.co.ke/v1/agent/chat/completions with an OpenAI-style body.
2. Receive HTTP 402 with a PAYMENT-REQUIRED header.
3. Sign the USDC payment on Base, retry with PAYMENT-SIGNATURE.
4. The response includes a receipt id. Read it at GET /v1/agent/receipts/{id}.

### Path B: agent-created account for a human
1. POST https://api.fikraapi.co.ke/v1/agents/accounts
```json
{"email":"human@example.com","agent_name":"my-agent","agent_version":"1.0","idempotency_key":"unique"}
```
2. The response contains account_id, token (6 hours), and claim_url.
3. Use Authorization: Bearer <token> for /v1/agents/*.
4. POST /v1/agents/keys with name, daily_cap_usd, monthly_cap_usd.
5. POST /v1/agents/topup with amount_usd to get a checkout link, or use x402 per call.
6. Give the human claim_url. They set a password and own the account.

### Path C: a prepaid key
The human creates an account at https://fikraapi.co.ke/account/signup, tops up, and gives you a key starting fk_live_. Send it as Authorization: Bearer fk_live_...

## Quote, call, receipt
Quote: POST /v1/agent/quote
```json
{"model":"deepseek-v4.1-flash-1017","messages":[{"role":"user","content":"Hello"}],"max_tokens":512}
```
Pass the returned quote_id to the call in the body or X-Fikra-Quote-Id.
Call: POST /v1/agent/chat/completions
Add stream: true for SSE. Agent chat is capped at 4096 output tokens.
The final SSE event is a receipt with usage, quoted USD, actual cost and receipt_id.
Receipt: GET https://api.fikraapi.co.ke/v1/agent/receipts/{receipt_id}

## Budgets
Create or update a key budget:
POST https://api.fikraapi.co.ke/v1/agents/keys/{key_id}/budget
```json
{"daily_cap_usd":5,"monthly_cap_usd":50}
```
A key over its cap returns HTTP 402 before the upstream call.

## Tools
Catalog: GET https://api.fikraapi.co.ke/v1/tools
Call: POST https://api.fikraapi.co.ke/v1/agent/tools/{name}
Each tool has a fixed price per job, not per token.

- extract_invoice: $0.25 per call. Extract invoice or receipt fields into structured JSON. No invented values.
- summarise_contract: $0.5 per call. Summarise a contract into parties, dates, obligations and risks. Not legal advice.
- screen_cv: $0.2 per call. Screen a CV against a job description into structured JSON. No protected-class inferences.

## MCP
Endpoint: POST https://api.fikraapi.co.ke/v1/mcp
Alias: POST https://api.fikraapi.co.ke/mcp
Tools: fikra_chat, fikra_list_models, fikra_quote, fikra_extract_invoice, fikra_summarise_contract, fikra_screen_cv.
Initialize with JSON-RPC, then tools/list and tools/call. Same wallet, key or x402 payment.

## A2A
Endpoint: POST https://api.fikraapi.co.ke/v1/a2a
Method: message/send. Non-streaming. Same account and price list.

## Status and usage
Status: GET https://fikraapi.co.ke/v1/status
Health: GET https://fikraapi.co.ke/v1/health
Public usage: GET https://fikraapi.co.ke/usage.json
Authenticated usage: GET https://fikraapi.co.ke/v1/usage
History: GET https://fikraapi.co.ke/v1/health-history

## Prices
Live machine-readable prices: GET https://api.fikraapi.co.ke/v1/models
Human table: https://fikraapi.co.ke/pricing

- deepseek-v4.1-flash: $0.05 in / $0.02 cached / $0.15 out per 1M tokens.
- deepseek-v4.1-flash-1017: $0.05 in / $0.02 cached / $0.15 out per 1M tokens.
- deepseek-v4-flash-0731: $0.05 in / $0.025 cached / $0.17 out per 1M tokens.
- glm-5.3-flash: $0.155 in / $0.08 cached / $0.49 out per 1M tokens.
- kimi-k3: $2.1 in / $0.6 cached / $10.5 out per 1M tokens.
- step-5-preview: $1.25 in / $same cached / $3.3 out per 1M tokens.
- mimo-v2.6-pro: $0.5 in / $0.012 cached / $1.0 out per 1M tokens.
- gemini-4-argon: $2.5 in / $same cached / $12.0 out per 1M tokens.
- glm-5.3: $1.05 in / $0.55 cached / $3.35 out per 1M tokens.
- glm-5.2: $0.75 in / $0.55 cached / $1.65 out per 1M tokens.
- nvidia-nemotron-3.5-super-vl: $0.5 in / $same cached / $1.25 out per 1M tokens.
- qwen3.8-27b: $0.045 in / $0.045 cached / $0.35 out per 1M tokens.
- fikra-pro-20b: $0.2 in / $same cached / $0.2 out per 1M tokens.
- fikra-pro-120b: $0.3 in / $same cached / $0.3 out per 1M tokens.
- fikra-qwen-27b: $0.045 in / $same cached / $0.35 out per 1M tokens.

## Limits
Unpaid: 30 requests/minute, 300/day, 100k tokens/minute, 1M tokens/day.
Paid: 3,000 requests/minute, 250k/day, no token ceilings.

## Errors
401 invalid or missing credentials. 402 payment required or budget reached. 429 rate limit. 502 upstream failure, retry with backoff. 503 service unavailable.

## Discovery
Agent card: https://api.fikraapi.co.ke/.well-known/agent-card.json
x402 manifest: https://fikraapi.co.ke/.well-known/x402.json
Agent accounts: https://fikraapi.co.ke/agents.json
Docs: https://docs.fikraapi.co.ke
OpenAPI: https://api.fikraapi.co.ke/openapi.json

## Safety
Never expose an API key in a prompt, log or client-side code.
Never send the claim_url by email unless the human asked you to.
Do not create accounts without a real, deliverable human email.
Do not bypass budgets or rate limits.

Start with a quote. Then pay. Then call. Then read the receipt.