Authentication & x402

Wallets, rails, payment requirements, retries, and production credential hygiene.

Owner

Developer Experience

Version

api-2026.07

Verified

2026-07-13

Mainnet launches with direct x402 as the public payment path. Each unpaid inference request returns an exact USDC quote, then the client signs and retries it. Invited service integrations may receive a fundedx-credit-key. Public market reads need no credential.

Choose a payment path

Invited service integrations

# Invited funded-key integrations can send one-call requests.
curl -N "$ROUTER_URL/v1/chat/completions" \
  -H "content-type: application/json" \
  -H "x-credit-key: $OMNIOUS_CREDIT_KEY" \
  -H "idempotency-key: ask-123" \
  -d '{"model":"auto","messages":[{"role":"user","content":"hello"}],"max_tokens":64}'

Public mainnet credit deposits and balance management are disabled at launch. A funded key is explicitly issued for an approved integration; ordinary API keys cannot spend. Give each agent its own key and budget.

Coding-agent integrations

Automated device setup is live on the mainnet launch: one command runs a device flow and your wallet approves a bounded spend key, as described in Integrations. Manual configuration with https://api.omnious.xyz and either a direct-x402 signer or an invited funded key remains available.

Mainnet x402 protocol

Direct x402 is the normal SDK or wallet integration path: an unpaid request intentionally returns 402 Payment Required, then a wallet signs the quoted authorization and the client retries. Do not paste the protocol placeholder into curl; use the SDK or the field-level wire format reference.

HTTP/1.1 402 Payment Required
content-type: application/json

{
  "x402Version": 2,
  "error": "payment required",
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:999",
    "maxAmountRequired": "550",
    "payTo": "0x<treasury>",
    "asset": "0x<USDC>",
    "maxTimeoutSeconds": 300
  }],
  "credits": {"header":"x-credit-key","required":"550","unit":"USDC base units",
    "note":"prepaid credits are spendable on inference and not currently withdrawable"}
}

Wallet and safety rules

• Keep x-credit-key server-side; it is a bearer credential that can spend its owner wallet's unified API balance within that key's cap.
• The unified API balance is spendable on inference and not currently withdrawable. Fund it in increments you expect to use; small refunds (session close-outs and per-request overage below the on-chain payout floor) are credited to this balance rather than broadcast on-chain, so they arrive instantly and gas-free but follow the same rule.
• Only typed-data signing is required; your wallet does not submit a transaction or pay gas.
• Amounts are USDC base units with six decimals: 550 is $0.000550.
• The signed amount must cover the router's quoted maximum. A lower amount is rejected before inference.
• Never log private keys, full payment envelopes, or x-credit-key values.

Authentication failures