x402 Payment Integration Guide
This page covers the payment mechanics for Nova Tools: headers, the 402 flow, accepted tokens, errors, and the facilitator. For how to connect an agent, discover tools, and the rate limits, see Using Nova Tools with AI Agents.
How It Works
The x402 protocol uses three HTTP headers to negotiate payment:
payment-required
Server β Client (402 response)
Base64-encoded payment requirements
payment-signature
Client β Server (retry request)
Base64-encoded signed payment
payment-response
Server β Client (200 response)
Base64-encoded settlement receipt
Flow Diagram
Client Server AIBTC Facilitator
β β β
ββββ POST /api/tools/:slug/run ββββββ>β β
β β β
β<ββ 402 + payment-required header ββββ β
β β β
β (client signs tx in wallet) β β
β β β
ββββ POST /run + payment-signature ββ>β β
β ββββ POST /verify ββββββββββββββ>β
β β<ββ { isValid: true } ββββββββββ
β β β
β β (executes tool) β
β β β
β ββββ POST /settle ββββββββββββββ>β
β β<ββ { success, txid } ββββββββββ
β β β
β<ββ 200 + payment-response header ββββ βStep-by-Step
Each step is shown in one language (curl or TypeScript); the other works the same way.
1. Call the Tool
2. Receive 402 Response
3. Sign Payment
Build a Stacks transaction for the chosen token. It must be sponsored (sponsored: true β the AIBTC relay pays gas) with zero fee (fee: 0n).
4. Retry with Payment
Repeat the request from step 1 with one extra header: payment-signature: <base64 payload>.
5. Receive Results
Supported Payment Tokens
All payments are on Stacks mainnet.
STX
Native
microSTX (1 STX = 1,000,000 uSTX)
sBTC
SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token
satoshis
USDCx
SP120SBRBQJ00MCWS7TM5R8WJNTTKD5K0HFRC2CNE.usdcx
base units
Error Handling
402
PAYMENT_REQUIRED
Payment needed β see accepts[] for options
400
PAYMENT_INVALID
Payment signature invalid or verification failed
400
VALIDATION_ERROR
Tool input validation failed
401
IDENTITY_REQUIRED
Must provide JWT or X-STACKS-ADDRESS for free tools
429
RATE_LIMITED
Too many requests β wait and retry
AIBTC Facilitator
Nova uses the AIBTC x402 Sponsor Relay for payment verification and settlement. The facilitator:
Verifies payment signatures match requirements
Sponsors transaction gas fees (gasless for the payer)
Broadcasts transactions to Stacks mainnet
Returns settlement receipts with txid
The facilitator is non-custodial β it can only execute transactions the client has already signed.
Premium Users
Nova Premium subscribers authenticate with a JWT and skip the x402 flow: paid tools run without per-call payment within the plan's monthly included-calls limit.
Last updated