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.

x402 is an HTTP-native payment protocol. Payment happens inline with the API call — no pre-registration, no API keys, no subscriptions.

---

How It Works

The x402 protocol uses three HTTP headers to negotiate payment:

Header	Direction	Content
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 ───│                                 │

Key safety feature: the flow is verify → execute → settle. Settlement only happens AFTER successful tool execution — if the tool fails, payment is never settled and your wallet is not charged.

---

Step-by-Step

Each step is shown in one language (curl or TypeScript); the other works the same way.

1. Call the Tool

curl -X POST https://nova.zeroauthoritydao.com/api/tools/stacks-token-analytics/run \
  -H "Content-Type: application/json" \
  -d '{"input": {"token": "WELSH"}}'

2. Receive 402 Response

HTTP/1.1 402 Payment Required
payment-required: eyJ4NDAyVmVyc2lvbiI6Mi4uLn0=
Content-Type: application/json

{
  "error": "PAYMENT_REQUIRED",
  "tool": {
    "slug": "stacks-token-analytics",
    "name": "Deep Token Analytics",
    "price_sats": 500
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "stacks:mainnet",
      "asset": "STX",
      "amount": "5000",
      "payTo": "SP...",
      "maxTimeoutSeconds": 300,
      "display": "~0.0050 STX"
    },
    {
      "scheme": "exact",
      "network": "stacks:mainnet",
      "asset": "SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token",
      "amount": "500",
      "payTo": "SP...",
      "maxTimeoutSeconds": 300,
      "display": "500 sats"
    },
    {
      "scheme": "exact",
      "network": "stacks:mainnet",
      "asset": "SP120SBRBQJ00MCWS7TM5R8WJNTTKD5K0HFRC2CNE.usdcx",
      "amount": "250",
      "payTo": "SP...",
      "maxTimeoutSeconds": 300,
      "display": "~$2.50"
    }
  ]
}

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).

import { makeSTXTokenTransfer } from '@stacks/transactions'

const tx = await makeSTXTokenTransfer({
  recipient: accept.payTo,
  amount: BigInt(accept.amount),
  senderKey: privateKey,
  network: 'mainnet',
  sponsored: true,
  fee: 0n,
})

const paymentPayload = {
  txid: tx.txid(),
  asset: 'STX',
  amount: accept.amount,
  from: senderAddress,
  to: accept.payTo,
  network: 'stacks:mainnet',
}

const paymentSignature = btoa(JSON.stringify(paymentPayload))

4. Retry with Payment

Repeat the request from step 1 with one extra header: payment-signature: <base64 payload>.

5. Receive Results

HTTP/1.1 200 OK
payment-response: eyJzdWNjZXNzIjp0cnVlLC4uLn0=
Content-Type: application/json

{
  "runId": "uuid",
  "status": "completed",
  "output": { ... }
}

---

Supported Payment Tokens

All payments are on Stacks mainnet.

Token	Contract	Unit
STX	Native	microSTX (1 STX = 1,000,000 uSTX)
sBTC	SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token	satoshis
USDCx	SP120SBRBQJ00MCWS7TM5R8WJNTTKD5K0HFRC2CNE.usdcx	base units

---

Error Handling

HTTP Status	Error Code	Meaning
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.