x402

Pay the gateway per token from a wallet — the 402 challenge, accepts negotiation, and the PAYMENT-SIGNATURE header.

x402 pays for inference per token from a wallet — no prepaid plan, no sign-up. The client and gateway settle it in three exchanges: a 402 challenge, a signed authorization, and a resend carrying that signature. For where x402 sits next to the workspace key and plan JWT, see Authentication.

Metered, on testnet

Settlement is metered — you pay for the tokens you actually used, never a flat estimate. x402 runs against Base testnet today, so treat amounts as test USDC.

Get the 402 PAYMENT-REQUIRED challenge

A request with no valid payment proof returns 402 with a challenge body instead of a run. The envelope declares the payment options — the client does not guess them:

{
  "x402Version": 2,
  "error": "payment required: authorize a USDC maximum to continue",
  "accepts": [
    { "scheme": "upto", "network": "base", "asset": "USDC" }
  ]
}

Pick a scheme from accepts

The accepts array lists the schemes the gateway will take for this request. The client picks one, builds the matching signed payload, and resends. Base offers two:

Scheme	How it settles
`upto`	Sign a USDC maximum (Permit2); the gateway runs the job, then settles only the tokens used — ≤ the max. The primary mode; it never over-collects.
`batch-settlement`	Settle the maximum up front to credit a prepaid balance, then meter many requests against it. A payment-channel for wallets that fund ahead.

Resend with the PAYMENT-SIGNATURE header

Resend the original request with a PAYMENT-SIGNATURE header — a base64 JSON payload carrying the chosen requirements, the signature, and the Permit2 authorization:

curl https://gateway.venna.net/v1/chat/completions \
  -H "PAYMENT-SIGNATURE: $VENNA_PAYMENT_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{ "model": "venna-fast", "messages": [{ "role": "user", "content": "ping" }] }'

One header serves every scheme — which one applies was settled in the 402 challenge. The Permit2 spender must be Venna's pinned x402 proxy (a foreign spender is rejected as no proof). A malformed or absent header re-issues the challenge rather than wedging the request.

Settlement guarantees

Capped — the settled amount can never exceed the signed maximum.
Metered — upto settles the real usage reported after generation; a high estimate refunds itself by settling less.
Idempotent — settlement is keyed to the single-use Permit2 nonce, so a replayed signature cannot double-charge.
Zero-cost aborts — a request that produces no usage settles 0, with no on-chain transaction.

Next steps

Authentication — how x402 compares to the workspace API key and the plan JWT.
Quickstart — the first-call path with a vk_ key if you would rather skip wallet payments.