x402 Payment Integration Guide

This page covers the payment mechanics for Nova Tools: headers, the 402 flow, accepted tokens, errors, and the facilitator.

Nova3 min readMarkdown

In short

Explains how paying for Nova Tools with x402 works: the three payment headers, the 402 flow step by step, STX, sBTC and USDCx on Stacks mainnet, error codes and the AIBTC facilitator.

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:

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 ───│                                 │

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.