x402 Protocol

The x402 protocol is an open standard. See the reference implementation at github.com/jinklabs/x402 (opens in a new tab).

Client                    API Server                 GullyPay Facilitator
|                           |                              |
|  1. GET /api/resource     |                              |
|-------------------------->|                              |
|                           |                              |
|  2. 402 Payment Required  |                              |
|  X-Payment: {requirements}|                              |
|<--------------------------|                              |
|                           |                              |
|  3. POST /x402/pay                                       |
|  {resource, txHash, amount, network, payerAddress}        |
|--------------------------------------------------------->|
|                           |                              |
|  4. {receiptToken}                                       |
|<---------------------------------------------------------|
|                           |                              |
|  5. GET /api/resource     |                              |
|  X-Payment-Receipt: token |                              |
|-------------------------->|                              |
|                           |  6. POST /x402/verify        |
|                           |  {receiptToken}              |
|                           |----------------------------->|
|                           |                              |
|                           |  7. {valid: true}            |
|                           |<-----------------------------|
|                           |                              |
|  8. 200 OK + resource     |                              |
|<--------------------------|                              |

{
"facilitator": "gullypay",
"x402Version": 1,
"supportedSchemes": ["exact"],
"supportedNetworks": ["base", "base-sepolia", "ethereum", "bsc", "solana", "gully-chain-testnet"],
"supportedAssets": ["USDC", "USDT", "GLUSD", "ETH", "WETH"],
"networks": {
  "gully-chain-testnet": {
    "network": "gully-chain-testnet",
    "chainId": 485590,
    "caip2": "eip155:485590",
    "name": "Gully Chain Testnet",
    "rpcUrl": "https://testnet-rpc.gullychain.xyz",
    "explorer": "https://testnet-explorer.gullychain.xyz",
    "txUrlTemplate": "https://testnet-explorer.gullychain.xyz/tx/{hash}",
    "assets": {
      "ETH": { "native": true, "address": null, "decimals": 18 },
      "WETH": { "native": false, "address": "0x26aCCCb2e98ca9e067E58668Aa3B101beF432754", "decimals": 18 }
    }
  }
}
}

{
"resource": "https://api.example.com/ai/generate",
"txHash": "0x7d1afa7b718fb893db30a3abc0cfc608aacfebb0",
"network": "base",
"amount": "100",
"payerAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD38"
}

{
"receiptToken": "rcpt_a1b2c3d4e5f6...",
"resource": "https://api.example.com/ai/generate",
"amount": "100",
"currency": "USDC",
"network": "base",
"expiresAt": "2025-06-09T13:00:00Z"
}

{
"receiptToken": "rcpt_a1b2c3d4e5f6..."
}

{
"valid": true,
"resource": "https://api.example.com/ai/generate",
"amount": "100",
"currency": "USDC",
"payer": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD38",
"network": "base",
"verifiedAt": "2025-06-09T12:01:00Z"
}

{
"receiptToken": "rcpt_a1b2c3d4e5f6...",
"reason": "Service unavailable"
}

{
"status": "refund_executed",
"receiptToken": "rcpt_a1b2c3d4e5f6...",
"amount": "100",
"refundTxHash": "0x9f2c...",
"reason": "Service unavailable"
}

Refunds move real funds and therefore require the platform settlement hot wallet to be configured. The refund settles on the same network as the original payment: EVM networks (Base / Ethereum / BSC) use the secp256k1 hot key (SETTLEMENT_WALLET_ENCRYPTED_KEY + SETTLEMENT_WALLET_ENCRYPTION_PASSWORD); Solana uses its own ed25519 hot key (SOLANA_SETTLEMENT_ENCRYPTED_KEY + SOLANA_SETTLEMENT_ADDRESS + SOLANA_RPC_URL) and returns the base58 transaction signature as refundTxHash. If the hot wallet for that network is not configured — or the on-chain transfer fails — the refund fails closed with 503 Service Unavailable and the payment is not marked refunded. No hash is ever fabricated.

{
"to": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD38",
"network": "base",
"asset": "USDC",
"amount": "1000000"
}

{
"id": "b3f1...",
"merchantId": "m_123",
"to": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD38",
"network": "base",
"asset": "USDC",
"amount": "1000000",
"txHash": "0x4a7b...",
"createdAt": "2026-07-18T12:00:00Z"
}

Payouts require the settlement hot wallet for the target network (same env as refunds — EVM secp256k1 key for Base/Ethereum/BSC, ed25519 key for Solana) and fail closed (503) when that network's wallet is unconfigured. POST /payouts is a manual primitive that pays the exact amount specified; for automated settlement use the owed-balance flow below.

[
{
  "network": "base",
  "asset": "USDC",
  "collected": "2000000",
  "fees": "20000",
  "refunded": "0",
  "alreadyPaid": "500000",
  "owed": "1480000"
}
]

{
"to": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD38",
"network": "base",
"asset": "USDC"
}

{
"urlPattern": "/api/v1/ai/generate",
"price": "100",
"currency": "USDC",
"scheme": "exact",
"network": "base",
"description": "AI text generation endpoint"
}

1import { GullyPayClient } from '@gullypay/x402-sdk';
2
3const client = new GullyPayClient({
4facilitatorUrl: 'https://gullypay.xyz/api',
5apiKey: 'rk_live_your_api_key',
6});
7
8// Automatic 402 handling -- the SDK detects 402 responses,
9// pays via the facilitator, and retries the request
10const response = await client.fetchWithPayment(
11'https://api.example.com/ai/generate',
12async (requirements) => {
13  return client.pay({
14    resource: requirements.resourceUrl,
15    txHash: '0x...',
16    network: requirements.network,
17    amount: requirements.price,
18    payerAddress: '0x742d35Cc...',
19  });
20},
21);
22
23const data = await response.json();
24console.log(data);

1from gullypay import GullyPayClient
2
3client = GullyPayClient(
4  facilitator_url="https://gullypay.xyz/api",
5  api_key="rk_live_your_api_key",
6)
7
8# Pay for a resource
9receipt = client.pay(
10  resource="https://api.example.com/ai/generate",
11  tx_hash="0x7d1afa7b718fb893db30a3abc0cfc608aacfebb0",
12  network="base",
13  amount="100",
14  payer_address="0x742d35Cc6634C0532925a3b844Bc9e7595f2bD38",
15)
16
17# Use the receipt to access the resource
18import requests
19
20response = requests.get(
21  "https://api.example.com/ai/generate",
22  headers={"X-Payment-Receipt": receipt.token},
23)
24
25print(response.json())

1import express from 'express';
2
3const FACILITATOR_URL = 'https://gullypay.xyz/api';
4
5function requirePayment(price: number, currency = 'USDC', network = 'base') {
6return async (req: express.Request, res: express.Response, next: express.NextFunction) => {
7  const receipt = req.headers['x-payment-receipt'] as string;
8
9  if (!receipt) {
10    // Return 402 with payment requirements
11    const requirements = {
12      price,
13      currency,
14      network,
15      facilitatorUrl: FACILITATOR_URL,
16      resourceUrl: `${req.protocol}://${req.get('host')}${req.originalUrl}`,
17    };
18
19    res.status(402)
20      .header('X-Payment', JSON.stringify(requirements))
21      .json(requirements);
22    return;
23  }
24
25  // Verify the receipt with the facilitator
26  const verification = await fetch(`${FACILITATOR_URL}/x402/verify`, {
27    method: 'POST',
28    headers: { 'Content-Type': 'application/json' },
29    body: JSON.stringify({ receiptToken: receipt }),
30  });
31
32  const result = await verification.json();
33
34  if (!result.valid) {
35    res.status(402).json({ error: 'Invalid payment receipt' });
36    return;
37  }
38
39  next();
40};
41}
42
43const app = express();
44
45// Protect an endpoint with x402 -- $0.01 per request
46app.get('/api/v1/ai/generate', requirePayment(100, 'USDC', 'base'), (req, res) => {
47res.json({ result: 'Your AI-generated content here' });
48});

{
"scheme": "metered",
"basePricePerUnit": 1,
"unit": "token",
"currency": "USDC",
"network": "base",
"estimatedUnits": 500,
"maxPrice": 1000,
"facilitatorUrl": "https://gullypay.xyz/api"
}

We recommend Base for most x402 integrations. It offers the lowest transaction fees and fastest settlement times while maintaining Ethereum-level security through optimistic rollups.

Every on-chain amount the facilitator stores or returns (price, payment amount, totalRevenue, timeseries revenue, fees, owed balances) is a decimal string of base units, exact up to 78 digits (uint256). Parse with BigInt, never Number.

On BSC, both USDC and USDT use 18 decimals (unlike the 6-decimal USDC on Base/Ethereum/Solana). Since an endpoint's price is denominated in the token's base units, price BSC endpoints accordingly (e.g. 0.02 USDT = 20000000000000000).

On Solana, submit the base58 transaction signature as txHash. For inbound verification the facilitator fetches the finalized transaction and confirms an SPL-token credit to the settlement wallet's associated token account by diffing pre/post token balances. Outbound settlement (refunds + payouts) is also supported on Solana: it signs an SPL transferChecked from the platform's ed25519 Solana hot wallet (creating the recipient's associated token account if needed) and returns the real base58 signature. glUSD on Solana uses its configured mint for both.