Payments

x402 uses an on-chain payment → credit model. Consumers make blockchain payments, receive credits, and spend those credits per RPC request.

---

How It Works

Step	Action
1	Platform defines pricing plans (payment asset → credit amount)
2	Consumer selects a plan and makes an on-chain payment
3	Gateway verifies the transaction on-chain
4	Credits are issued to the consumer's wallet
5	Each RPC call deducts credits before execution
6	Requests with zero credits receive 402 Payment Required

---

Listing Pricing Plans

Retrieve available plans from the gateway:

GET /pricing
Authorization: Bearer <your-token>

Response:

{
  "plans": [
    {
      "id": "plan_starter",
      "name": "Starter",
      "asset": "USDC",
      "chain": "ethereum",
      "amount": "10.00",
      "credits": 10000,
      "price_per_credit": "0.001"
    },
    {
      "id": "plan_pro",
      "name": "Pro",
      "asset": "USDC",
      "chain": "ethereum",
      "amount": "50.00",
      "credits": 60000,
      "price_per_credit": "0.00083"
    }
  ]
}

---

Initiating a Payment

Select a plan and get payment details:

POST /payments/initiate
Authorization: Bearer <your-token>
Content-Type: application/json

{
  "plan_id": "plan_starter",
  "wallet_address": "0xYourAddress"
}

Response:

{
  "payment_id": "pay_abc123",
  "recipient": "0xGatewayTreasuryAddress",
  "asset": "USDC",
  "amount": "10.00",
  "chain_id": 1,
  "expires_at": "2024-06-01T12:15:00Z"
}

Make the on-chain transfer to the recipient address using your wallet.

---

Confirming a Payment

After broadcasting the transaction, submit the tx hash:

POST /payments/confirm
Authorization: Bearer <your-token>
Content-Type: application/json

{
  "payment_id": "pay_abc123",
  "tx_hash": "0x9f3a..."
}

The gateway verifies the transaction on-chain. Once confirmed:

{
  "status": "confirmed",
  "credits_issued": 10000,
  "new_balance": 10000
}

---

Checking Credit Balance

GET /credits/balance
Authorization: Bearer <your-token>

{
  "address": "0xYourAddress",
  "credits": 9750,
  "last_updated": "2024-06-01T12:30:00Z"
}

---

Credit Consumption

Credits are deducted before each RPC request is executed. Deduction amounts depend on the method type:

Method Type	Example Methods	Credits
Standard reads	eth_call, eth_blockNumber, eth_getBalance	1
Historical queries	eth_getLogs, eth_getStorageAt	5
Write methods	eth_sendRawTransaction	10

INFO

Batch requests consume credits for each individual method call included in the batch.

---

402 Payment Required

When credits are exhausted, the gateway returns:

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "error": "INSUFFICIENT_CREDITS",
  "message": "Your credit balance is 0. Top up to continue.",
  "credits_required": 1,
  "credits_available": 0,
  "payment_url": "/pricing"
}

This response is machine-readable — autonomous agents and application code can detect it and initiate a top-up automatically.

---

Payment History

View your payment and credit transaction history:

GET /payments/history
Authorization: Bearer <your-token>

{
  "payments": [
    {
      "id": "pay_abc123",
      "plan": "Starter",
      "amount": "10.00 USDC",
      "credits": 10000,
      "status": "confirmed",
      "created_at": "2024-06-01T12:00:00Z"
    }
  ]
}

---

Plan Comparison

Plan	Asset	Amount	Credits	Cost per Credit
Starter	USDC	$10.00	10,000	$0.001
Pro	USDC	$50.00	60,000	$0.00083
Enterprise	Custom	Custom	Custom	Negotiated