---
id: build/x402
title: "x402 Payment Integration Guide"
description: "This page covers the payment mechanics for Nova Tools: headers, the 402 flow, accepted tokens, errors, and the facilitator."
product: nova
canonical: https://zeroauthoritydao.ai/docs/build/x402
related: [build]
tokens: 1554
---

# x402 Payment Integration Guide

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](https://zeroauthoritydao.ai/docs/build/nova-tools-for-agents.md).

> [!NOTE]
> 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 ───│                                 │
```

> [!TIP]
> **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

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