Developer reference
Model discovery, chat completions and prepaid account credits.
The endpoint reference below uses the same contract as the downloadable OpenAPI document. Check service status before testing sign-in or funding.
curl --fail-with-body https://www.oma-ai.com/api/v1/modelsSet OMA_API_KEY to your saved secret. Replace the example model if the live catalog reports it unavailable.
curl --fail-with-body https://www.oma-ai.com/api/v1/chat/completions \
-H "Authorization: Bearer $OMA_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"model":"minimax-m2-7","max_tokens":256,"messages":[{"role":"user","content":"Hello!"}]}'SDK base URL: https://www.oma-ai.com/api/v1. All API-key inference spends credits, including models offered free in website chat.
Send Authorization: Bearer $OMA_API_KEY. The Messages endpoint also accepts x-api-key. Keep keys on your server. Create, list and revoke keys using a signed-in session, not another API key.
Email sign-in uses a magic link. Wallet sign-in uses SIWE. Account, key-management and x402 settlement routes require the session cookie specified in the endpoint reference.
Key expiry, model scope and IP restrictions are defined under POST /v1/keys. Invalid explicit credentials are rejected instead of falling back to guest access. Cookie-authenticated mutations also require an allowed Origin or Referer. Browsers send it automatically; scripts must set Origin: https://www.oma-ai.com.
For clients using Chat Completions, configure the base URL above and an OMA catalog model ID. The gateway does not implement the OpenAI Responses API.
For the supported Anthropic Messages subset, use base URL https://www.oma-ai.com/api when the client appends /v1/messages. Text and function tools are supported; image/document blocks are rejected. Extended thinking and prompt-cache fields are ignored and not forwarded.
curl --fail-with-body https://www.oma-ai.com/api/v1/messages \
-H "x-api-key: $OMA_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"model":"minimax-m2-7","max_tokens":256,"messages":[{"role":"user","content":"Hello!"}]}'Client-specific configuration files vary by version. Configure the endpoint, key and model through that client's documented custom-provider settings.
Paths below are relative to https://www.oma-ai.com/api. Funding paths /x402/* are relative to https://www.oma-ai.com. Optional fields, bounds, authentication and response formats are shown per operation.
GET /userCurrent account profileSigned-in session cookie
application/json · fields: id, email, name, evmAddress, isAnonymous, role, createdAt
GET /sessionsList active sessionsSigned-in session cookie
application/json · fields: sessions
DELETE /sessionsRevoke all other sessions, retaining the current sessionSigned-in session cookie
Required unless Referer supplies the allowed website origin, including when a Bearer key is used. Browsers send this automatically. Scripts must send Origin matching the website (production: https://www.oma-ai.com). Missing or disallowed origin returns 403 csrf_error.
string · format: "uri"application/json · fields: success, revokedCount
DELETE /sessions/{id}Revoke an owned remote sessionSigned-in session cookie
stringRequired unless Referer supplies the allowed website origin, including when a Bearer key is used. Browsers send this automatically. Scripts must send Origin matching the website (production: https://www.oma-ai.com). Missing or disallowed origin returns 403 csrf_error.
string · format: "uri"application/json · fields: success, id
DELETE /accountPermanently delete the current accountSigned-in session cookie
Requires a session created within the last 24 hours. Deletes identity, sessions, API keys, usage and operational deposit/balance rows; forfeits remaining credits. Detached inference financial receipts and security audit records remain for reconciliation. Clears session and installed API-key cookies.
Required unless Referer supplies the allowed website origin, including when a Bearer key is used. Browsers send this automatically. Scripts must send Origin matching the website (production: https://www.oma-ai.com). Missing or disallowed origin returns 403 csrf_error.
string · format: "uri"application/json · fields: success
DELETE /v1/historyClear usage history and previous audit logsSigned-in session cookie
Preserves identity, API keys, sessions, and balances. Records a new HISTORY_CLEARED audit event.
Required unless Referer supplies the allowed website origin, including when a Bearer key is used. Browsers send this automatically. Scripts must send Origin matching the website (production: https://www.oma-ai.com). Missing or disallowed origin returns 403 csrf_error.
string · format: "uri"application/json · fields: success, deleted
GET /v1/modelsList the model catalogPublic
application/json · fields: object, data
POST /v1/chat/completionsOpenAI-compatible chat completion (streaming + tool calls)Signed-in session cookie or Authorization: Bearer API key or x-api-key header
Only the documented request fields are forwarded. Unknown fields, including reasoning_effort, response_format, stop and max_completion_tokens, are currently ignored. API key model restrictions apply to primary and fallback routes. max_tokens cannot exceed the model's configured max_output_tokens. Idempotency-Key prevents concurrent upstream calls across both API formats; completed keys return 409 without another call or charge. Completion bodies are not retained for replay.
Account-scoped retry key, at most 512 UTF-8 bytes. Use a new key for a new request; retain your original response.
string · min length: 1 · max length: 512| Field | Contract |
|---|---|
| model * | Primary OMA catalog model id string |
| models | OpenRouter-style fallback chain tried after `model` fails (before server peer map). Response `model` + x-actual-model reflect the peer that served. array · max items: 8 Full field schema |
| messages * | array · min items: 1 · items: ChatMessage Full field schema |
| max_tokens | Positive completion budget; must fit the selected model’s max_output_tokens. If omitted, defaults to the smaller of 4096 and the model output ceiling. integer · min: 1 |
| stream | boolean · default: false |
| temperature | number · min: 0 · max: 2 |
| top_p | number · min: 0 · max: 1 |
| tools | array |
| tool_choice | any JSON value |
* Required. JSON Schema keywords show accepted types and bounds.
application/json
text/event-stream
POST /v1/messagesAnthropic-compatible Messages APISigned-in session cookie or Authorization: Bearer API key or x-api-key header
Unknown request fields are ignored and not forwarded. Text and tool-use Anthropic Messages requests, translated to the same OMA provider routing and credit ledger. Image/document content blocks are not supported. max_tokens is required and must fit the selected model. Idempotency-Key is account-scoped and shared with chat completions; completed responses are not retained for replay.
At most 512 UTF-8 bytes. Use a new value for each new request.
string · min length: 1 · max length: 512| Field | Contract |
|---|---|
| model * | OMA catalog model ID string |
| messages * | array · min items: 1 Full field schema |
| system | any JSON value Full field schema |
| max_tokens * | integer · min: 1 |
| temperature | number · min: 0 · max: 1 |
| top_p | number · min: 0 · max: 1 |
| stream | boolean · default: false |
| tools | array Full field schema |
| tool_choice | any JSON value Full field schema |
* Required. JSON Schema keywords show accepted types and bounds.
application/json · fields: id, type, role, model, content, stop_reason, stop_sequence, usage
text/event-stream
GET /v1/balanceCurrent credit balance (cents)Signed-in session cookie or Authorization: Bearer API key or x-api-key header
application/json · fields: userId, balanceCents, debtCents, totalDepositedCents, totalUsedCents, reservedCents, reconciliationCents, lastActivityAt
GET /v1/usagePaginated per-request usage history (model, provider, API key, token counts, cents)Signed-in session cookie or Authorization: Bearer API key or x-api-key header
Private account history. Treat next_cursor as opaque and pass it unchanged. Totals cover every record matching the filters, independent of the cursor. totalCents is the original charge; billedCents is zero after a refund, with refundedAt preserving its timestamp. Monetary values are decimal-string cents.
string · max length: 150string · allowed: "venice", "oma-ai"string · format: "uuid"string · format: "date-time"string · format: "date-time"integer · min: 1 · max: 500 · default: 50string · max length: 512application/json · fields: object, data, next_cursor, totals
GET /v1/usage/summaryComplete account statistics, model/provider breakdowns and chart bucketsSigned-in session cookie or Authorization: Bearer API key or x-api-key header
Full-range aggregates, independent of request pagination. range is a rolling window; last24h always covers the preceding 24 hours. Billed cents exclude refunded charges, errors and cancellations are counted separately. Timeline includes zero buckets in the requested IANA timezone; all uses monthly buckets. Response contains range, timezone, bucket, from (null for all), to, lifetimeRequests, totals, last24h, models, providers and timeline. Each totals object includes requests, errors, aborted, free_requests, active_models, input_tokens, output_tokens, billed_cents (decimal string) and avg_latency_ms. Use from/to as since/until when loading the matching request history.
string · default: "7d" · allowed: "24h", "7d", "30d", "all"IANA timezone, e.g. America/Moncton
string · max length: 100 · default: "UTC"application/json · fields: range, timezone, bucket, from, to, totals, last24h, lifetimeRequests, models, providers, timeline
GET /v1/keysList active API keysSigned-in session cookie
Lists key metadata including expiresAt, allowedModels and ipAllowlist. Expired keys can remain listed until revoked; they cannot authenticate. Never returns a raw key.
application/json · fields: keys
POST /v1/keysMint a new API key (returned once)Signed-in session cookie
Requires a Better Auth session, not an API bearer key. Raw key is returned once. Restrictions apply to both primary models and fallback routes. Default expiry is 90 days.
Required unless Referer supplies the allowed website origin, including when a Bearer key is used. Browsers send this automatically. Scripts must send Origin matching the website (production: https://www.oma-ai.com). Missing or disallowed origin returns 403 csrf_error.
string · format: "uri"| Field | Contract |
|---|---|
| name | string · min length: 1 · max length: 64 · default: "default" |
| expiresInDays | integer · min: 1 · max: 365 · default: 90 |
| allowedModels | OMA catalog IDs. Omit to allow all models. array · min items: 1 · max items: 30 Full field schema |
| ipAllowlist | IPv4/IPv6 addresses or CIDR ranges. Only matching callers can use the key. Include your server's public outbound IP. Omit for unrestricted access. array · min items: 1 · max items: 20 Full field schema |
* Required. JSON Schema keywords show accepted types and bounds.
application/json
DELETE /v1/keys/{id}Revoke an API keySigned-in session cookie
string · format: "uuid"Required unless Referer supplies the allowed website origin, including when a Bearer key is used. Browsers send this automatically. Scripts must send Origin matching the website (production: https://www.oma-ai.com). Missing or disallowed origin returns 403 csrf_error.
string · format: "uri"application/json · fields: success, id
GET /v1/deposit/usdcUSDC deposit instructionsSigned-in session cookie or Authorization: Bearer API key or x-api-key header
application/json · fields: depositAddress, network, chainId, usdcContract, minDepositCents, maxDepositCents, creditsPerCent
POST /v1/deposit/usdcRecord a signed USDC deposit for confirmationSigned-in session cookie or Authorization: Bearer API key or x-api-key header
First obtain a challenge, then sign the canonical deposit authorization message binding the sending wallet, deposit address, challengeToken, transaction hash and amountUsd. Returns pending without crediting; the watcher verifies the transfer. Amount must also fit the current minDepositCents/maxDepositCents instructions. No transfer is initiated by this endpoint.
Required unless Referer supplies the allowed website origin, including when a Bearer key is used. Browsers send this automatically. Scripts must send Origin matching the website (production: https://www.oma-ai.com). Missing or disallowed origin returns 403 csrf_error.
string · format: "uri"| Field | Contract |
|---|---|
| amountUsd * | USD amount, not cents. Current configured deposit bounds also apply. number · greater than: 0 · max: 10000 |
| txHash * | string Full field schema |
| network | string · default: "base" · allowed: "base" |
| fromAddress * | string Full field schema |
| challengeToken * | string · min length: 20 |
| signature * | string · min length: 2 |
* Required. JSON Schema keywords show accepted types and bounds.
application/json · fields: depositId, status, amountCents, txHash, network, message
POST /v1/deposit/usdc/challengeRequest a short-lived deposit ownership challengeSigned-in session cookie or Authorization: Bearer API key or x-api-key header
The returned token is bound to the authenticated account and funding wallet and expires after five minutes. Pass token as challengeToken in the signed deposit submission. The signature must bind the transaction and amount in addition to this challenge.
Required unless Referer supplies the allowed website origin, including when a Bearer key is used. Browsers send this automatically. Scripts must send Origin matching the website (production: https://www.oma-ai.com). Missing or disallowed origin returns 403 csrf_error.
string · format: "uri"| Field | Contract |
|---|---|
| fromAddress * | string Full field schema |
* Required. JSON Schema keywords show accepted types and bounds.
application/json · fields: token, nonce, expiresAt
GET /v1/deposit/statusList the authenticated account’s latest depositsSigned-in session cookie or Authorization: Bearer API key or x-api-key header
Returns up to 50 owner-scoped deposits, newest first. No requestId or userId parameter is accepted. amountUsd is a decimal string in dollars; creditsIssued is a decimal string in cents.
application/json · fields: deposits
GET /v1/usage/todayToday's free-chat quota (guest IP or signed-in account)Signed-in session cookie or Authorization: Bearer API key or x-api-key header or
Optional session or API-key authentication. Counts admitted free-chat attempts, including upstream failures; this read does not consume quota. Resets at midnight UTC. Paid API-key inference uses prepaid credits instead. Redis outages use bounded, process-local counters retaining observed usage; these are not durable across restarts.
application/json · fields: used, limit, remaining, resetMs, policy
POST /v1/checkoutCreate a Polar checkout for a prepaid credit packSigned-in session cookie or Authorization: Bearer API key or x-api-key header
Choose a configured plan. successUrl is optional; only allowed app origins are honored, otherwise the server uses its dashboard success URL. The Polar webhook delivers credits after payment. productId and cancelUrl are not request fields.
Required unless Referer supplies the allowed website origin, including when a Bearer key is used. Browsers send this automatically. Scripts must send Origin matching the website (production: https://www.oma-ai.com). Missing or disallowed origin returns 403 csrf_error.
string · format: "uri"| Field | Contract |
|---|---|
| plan * | string · allowed: "hobby", "builder", "scale" |
| successUrl | string · format: "uri" |
* Required. JSON Schema keywords show accepted types and bounds.
application/json · fields: id, url, plan, creditsOnSuccess
GET /v1/credits/balancePrepaid balance, credit holds and active batchesSigned-in session cookie or Authorization: Bearer API key or x-api-key header
application/json · fields: activeBatches, balanceCents, debtCents, reservedCents, reconciliationCents
GET /v1/credits/transactionsCredit transaction history (deposits, usage, refunds)Signed-in session cookie or Authorization: Bearer API key or x-api-key header
integer · min: 1 · max: 200 · default: 50application/json · fields: transactions
POST /v1/refundsRequest a full usage-charge credit refund for operator reviewSigned-in session cookie or Authorization: Bearer API key or x-api-key header
Paid charges within 30 days only. At most five pending per account and one per usage charge. Approval restores OMA credits; it does not issue a card/USDC payment. Partial refunds are not supported.
Required whenever cookies accompany the request, including when a Bearer key is selected, unless Referer supplies the allowed website origin. Not required for cookie-free Bearer API-key refunds. Missing or disallowed browser origin returns 403 csrf_error.
string · format: "uri"| Field | Contract |
|---|---|
| usageId * | string · format: "uuid" |
| reason * | string · min length: 10 · max length: 1000 |
| amountCents | Optional exact full-charge amount in cents, including fractional cents. Omit to use the original charge. number · greater than: 0 |
* Required. JSON Schema keywords show accepted types and bounds.
application/json · fields: id, usageId, amountCents, status, createdAt
GET /v1/refundsList the caller's refund requests (newest first)Signed-in session cookie or Authorization: Bearer API key or x-api-key header
string · allowed: "pending", "granted", "denied"integer · min: 1 · max: 200 · default: 50application/json · fields: data, creditRefundsAvailable
GET /v1/export/usageExport usage as CSV or JSONSigned-in session cookie
Owner-scoped usage, newest first, at most 10,000 rows. since must not exceed until. Monetary columns are decimal-string cents. Includes billed_cents/refunded_at. X-Export-Row-Count and X-Export-Truncated report the export bound. model, from and to are not filters.
string · default: "csv" · allowed: "csv", "json"string · format: "date-time"string · format: "date-time"text/csv
application/json
GET /v1/export/depositsExport recorded deposits as CSV or JSONSigned-in session cookie
Latest 10,000 deposit rows for the authenticated account. amount_usd is dollars; credits_issued is cents. This exports deposits, not credit batches or expiration grants. format=json selects JSON; all other values produce CSV.
Use json for JSON; otherwise CSV.
string · default: "csv"text/csv
application/json
GET /v1/export/summaryExport all-time account totals as CSV or JSONSigned-in session cookie
All-time balance, deposited/used cents, request/token totals and non-refunded usage charges. No date-range filters are supported. format=json selects JSON; all other values produce CSV.
Use json for JSON; otherwise CSV.
string · default: "csv"text/csv
application/json
GET /v1/export/accountJSON export of full account state (profile, balance, keys metadata, settings)Signed-in session cookie
application/json · fields: exportedAt, format, profile, apiKeys, usageRecords, deposits, creditBalance, auditLogs, sessions
GET /v1/models/{id}Get a single model from the catalogPublic
stringapplication/json · fields: id, object, created, owned_by, privacy, architecture, metadata_verification, available, unavailable_reason, unavailable_cause, context_length, max_output_tokens, supports_streaming, supports_tools, capabilities, pricing
GET /readyDatabase and Redis readiness probePublic
application/json · fields: status, service, uptimeSec, checks
application/json · fields: status, service, uptimeSec, checks
GET /versionPublic application versionPublic
application/json · fields: version, service
GET /v1/searchWeb search (chat playground grounding)Public
Optional auth. DuckDuckGo HTML + Instant Answer (no API key). Returns { query, results, provider: "duckduckgo" }; empty results on total failure.
string · min length: 1 · max length: 500application/json · fields: query, provider, results
GET /x402/infoDiscover the current x402 funding recipient and signing informationPublic
Read payTo, network, and asset before signing; the direct-deposit address may differ. Choose the funding amount yourself. This request does not move funds.
application/json · fields: x402Version, scheme, network, asset, decimals, payTo, maxAtomicAmount, maxTimeoutSeconds, extra
POST /x402/verifyVerify and broadcast an EIP-3009 USDC transferPublic
Moves the authorized USDC to the pinned treasury and waits for on-chain confirmation; this is not a dry run. The facilitator pays gas. Save the returned txHash, then call /x402/settle with the payer wallet's SIWE session to credit the account. Rate-limited at 10/min/IP. Funding is capped by USDC_DEPOSIT_MAX_CENTS ($10,000 default); read maxAtomicAmount from /x402/info. Oversized authorizations return 400 x402_funding_limit before transfer verification or broadcast. Positive fractional USDC remains accepted. Returns 503 funding_paused or funding_status_unavailable before moving funds when new crypto funding is unavailable. Existing transfers can still be credited through /x402/settle during a funding pause.
Base64-encoded x402 v2 envelope containing accepted requirements and the signed EIP-3009 authorization.
stringPOST /x402/settleCredit a confirmed USDC payment to the authenticated payerSigned-in session cookie
Does not initiate another transfer. Requires a SIWE session for the payment sender; an API key is not accepted. Uses the confirmed amount, never a caller-supplied amount. Retries for the same account and transaction credit once; confirmed payments can be recovered after a server restart. Limited to 30 requests per minute per account and client IP; honor Retry-After on HTTP429.
| Field | Contract |
|---|---|
| txHash * | string Full field schema |
| networkId * | string · allowed: "base", "eip155:8453" |
* Required. JSON Schema keywords show accepted types and bounds.
GET /healthLiveness probePublic
application/json · fields: status, service, timestamp
GET /v1/healthLiveness probe (v1-prefixed alias)Public
Same payload as GET /health, exposed under /v1 so SDK-style callers that prepend /v1 to every path get a real 200.
application/json · fields: status, service, timestamp
Limits below are the configured gateway limits. Provider verification and pricing sources are linked on each model page. OMA/OpenBroker limits whose upstream API does not publish specifications are marked unverified there. Use the live model API for runtime availability and price overrides.
| API model ID | Context tokens | Max output tokens |
|---|---|---|
| openai-gpt-56-sol | 1,000,000 | 128,000 |
| claude-opus-5 | 1,000,000 | 128,000 |
| kimi-k3 | 1,000,000 | 131,072 |
| zai-org-glm-5-2 | 1,000,000 | 131,072 |
| deepseek-v4-pro | 1,000,000 | 32,768 |
| qwen-3-8-max | 1,000,000 | 131,072 |
| grok-4-5 | 500,000 | 32,000 |
| claude-sonnet-4-6 | 1,000,000 | 64,000 |
| gemini-3-6-flash | 1,000,000 | 65,536 |
| llama-3.3-70b | 128,000 | 4,096 |
| hermes-3-llama-3.1-405b | 128,000 | 16,384 |
| zai-org-glm-5-1 | 200,000 | 80,000 |
| qwen-3-7-plus | 1,000,000 | 65,536 |
| venice-uncensored-1-2 | 128,000 | 8,192 |
| xiaomi-mimo-v2-5 | 1,000,000 | 65,536 |
| deepseek-v4-flash-0731 | 1,000,000 | 32,768 |
| google-gemma-4-31b-it | 256,000 | 8,192 |
| minimax-m2-7 | 180,000 | 16,384 |
| deepseek-v4-flash-0731-openbroker | 400,000 | 16,384 |
| zai-org-glm-5-3 | 400,000 | 16,384 |
Requested output must fit the selected model's output limit. Input plus requested output must fit the gateway context check; its input count is an estimate. A provider can reject a request that its tokenizer counts differently.
Select the exact API ID. The optional models array supplies up to eight fallback IDs. API-key restrictions apply to fallback routes. Inspect x-actual-model and the response model when a fallback serves the request.
Venice model privacy is shown per model as private or anonymized using the provider catalog. OMA-AI routes use OpenBroker. Catalog availability describes configured access and pauses; it is not a guarantee of provider health.
Set stream: true. Chat Completions returns SSE data chunks and [DONE]. Messages uses Anthropic-shaped SSE events. An error after response headers can arrive inside the stream, so handle stream errors as well as HTTP failures.
curl --no-buffer --fail-with-body https://www.oma-ai.com/api/v1/chat/completions \
-H "Authorization: Bearer $OMA_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"model":"minimax-m2-7","max_tokens":256,"stream":true,"messages":[{"role":"user","content":"Hello!"}]}'Keep the response and X-OMA-Request-ID. Stop reading when your application cancels the request. A partial response can still incur usage charges.
Inference has a 60-request limit per 60 seconds by client IP. The default model limiter uses a 60-request bucket refilling at 20 requests per second, with a 60-request sliding minute ceiling.
The models below instead enforce independent model budgets by account, key and IP. Their token budget counts estimated input plus requested max_tokens, not actual billed usage.
| Model | Requests/minute | Tokens/minute |
|---|---|---|
| llama-3.3-70b | 60 | 120,000 |
| deepseek-v4-flash-0731-openbroker | 60 | 120,000 |
| kimi-k3 | 60 | 120,000 |
| minimax-m2-7 | 60 | 120,000 |
| zai-org-glm-5-3 | 60 | 120,000 |
When Redis is unavailable, the model limiter permits 5 requests per minute per account and instance, or per IP for guests. Exhaustion returns 503. Script failures can use a bounded local counter; X-RateLimit-Policy includes degraded-memory.
Eligible free website chat allows 20 attempts per UTC day for guests by IP, or 100 for signed-in users. Attempts are reserved before inference and reset at UTC midnight. API keys bypass the free allowance and use paid credits. Exhaustion returns 429.
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and X-RateLimit-Policy describe the current limiting layer. Reset is Unix seconds. Retry-After is seconds. Free chat also returns X-DailyLimit-*. Search and funding have separate limits in their operation descriptions.
Prices are USD per million tokens. Live /v1/models returns the actual retail input/output rates and any extended-context tier. For a request, input cost plus output cost equals tokens divided by 1,000,000 times each applicable rate.
Balances and charges use decimal-string cents, preserving fractional cents. Paid inference temporarily reserves the full configured input-context cost plus the requested output budget, including eligible fallback routes, before upstream work. A request can require more available credits than its final charge. Unused credits return after the cost is confirmed. Interrupted or uncertain requests can retain a budget for review. Use a reasonable max_tokens to bound cost. Free website chat and paid API usage are separate policies.
A cash refund removes the corresponding prepaid credits. If those credits were spent or reserved, the account can have a credit shortfall. Spendable balanceCents stays at zero whiledebtCents reports the shortfall in decimal-string cents. Future top-ups first offset it before credits become available to spend.
Current configured retail examples: minimax-m2-7: $0.02 input / $0.02 output; deepseek-v4-flash-0731-openbroker: $0.02 input / $0.02 output; zai-org-glm-5-3: $0.02 input / $0.02 output. See all prices.
POST /x402/verify moves money. It verifies a signed EIP-3009 authorization, broadcasts the USDC transfer and waits for confirmation. It is not a dry run. Base mainnet is the supported network.
/x402/info.PAYMENT-SIGNATURE to /x402/verify. Save any returned transaction hash, including one in a timeout response./x402/settle with the hash, network ID and the payer's SIWE session. Settlement credits the confirmed transfer and does not send another payment.If crediting fails, retry settlement with the same hash and payer session. Inspect on-chain evidence before signing any replacement payment. A 409 reconciliation conflict requires support, not another payment. New funding fails closed when account/payment availability cannot be checked.
Direct deposits can use a different treasury address. Always use the instructions returned by the chosen funding method. On-chain confirmation and account crediting are separate steps.
Send Idempotency-Key for inference retries, up to 512 UTF-8 bytes. Keys are scoped to the account across both formats. A duplicate in progress returns 409 request_in_progress with Retry-After: 5. A completed key returns 409 already_processed, without replaying the body. Retain the original response.
The application executes tools. Send the assistant tool calls and corresponding results back in the next request. Validate arguments and cap tool turns. Each model request uses its own budget and charge.
Model discovery requires no key. Choose a Chat Completions client rather than a client that requires the Responses API.
Gateway errors generally use {"error":{"message":"…","type":"…","code":"…"}}. Some fields are optional. Validation errors can include issues; provider bodies and in-stream failures can differ.
Honor Retry-After and cap retries. Do not retry invalid requests unchanged. Do not authorize another payment to fix a settlement conflict. Report the inference request ID when asking for help.