> For the complete documentation index, see [llms.txt](https://docs.zeroauthority.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zeroauthority.xyz/nova-bot/nova-tools/x402-payment-integration-guide.md).

# 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](/nova-bot/nova-tools/using-nova-tools-with-ai-agents.md).

{% hint style="info" %}
x402 is an HTTP-native payment protocol. Payment happens inline with the API call — no pre-registration, no API keys, no subscriptions.
{% endhint %}

***

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

{% hint style="success" %}
**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.
{% endhint %}

***

## Step-by-Step

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

### 1. Call the Tool

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

```typescript
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
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](https://x402-relay.aibtc.com) 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.