Skip to main content

Pay-Per-Request

Mode: Direct
In the Pay-Per-Request (or “Direct”) model, agents pay for each individual API call or digital good download at the moment of request. This flow uses the standard HTTP 402 Payment Required status code to negotiate payment.

Interaction Cycle

1. The “Naïve” Request

The agent attempts to access the resource or API endpoint without any payment headers.
curl -X GET https://api.x402layer.cc/e/super-ai-trader

2. The 402 Challenge

The server negotiates by returning 402 Payment Required and a JSON body detailing the price, asset, and destination.
// HTTP 402 Payment Required
{
  "x402Version": 1,
  "accepts": [
    {
      "network": "base",                 // or "solana"
      "asset": "base:8453/erc20:0x...", // Token Identifier
      "chainId": 8453,
      "payTo": "0x742d35Cc6...",        // Destination Wallet
      "maxAmountRequired": "1000000",   // Amount in lowest unit (e.g. Wei/Lamports)
      "purchaseUrl": "..."              // Human page fallback
    }
  ]
}

3. The Authorized Request

The agent constructs and signs a transaction matching the requirements, then resends the request with the X-Payment header.
curl -X GET https://api.x402layer.cc/e/super-ai-trader \
  -H "X-Payment: eyJ4NDAyVmVyc2lvbiI6MSwic2NoZW1lIjoiZXhhY3QiLi4ufQ=="

Transaction Construction

The critical step is building the correct transaction. The format differs strictly between EVM (Base) and Solana.
Rule: You MUST construct an ERC-20 transfer of the specified asset (USDC). Native ETH transfers are ignored.
# Python (Web3.py)

# 1. Parse 'asset' from 402 response
# Format: "base:8453/erc20:0x..."
token_address = accept['asset'].split(':')[-1]

# 2. Build ERC-20 Transfer
contract = w3.eth.contract(address=token_address, abi=ERC20_ABI)
tx = contract.functions.transfer(
    accept['payTo'],               # Destination from 402
    int(accept['maxAmountRequired']) # Amount from 402
).build_transaction({
    'chainId': 8453,
    'gas': 100000,
    'nonce': w3.eth.get_transaction_count(agent_address),
    'gasPrice': w3.eth.gas_price
})

# 3. Sign locally
signed_tx = w3.eth.account.sign_transaction(tx, private_key)

# 4. Serialize for Header
raw_hex = signed_tx.rawTransaction.hex() # "0x..."

x-Payment Header

Once you have the serialized, signed transaction (hex for EVM, base64 for Solana), wrap it in the payment object and Base64 encode the whole thing.
// The JSON Object
{
  "x402Version": 1,
  "scheme": "exact",
  "network": "base", // or "solana"
  "payload": {
    "serializedTransaction": "0x..." // or base64 string for solana
  }
}

// Final Header Value
// Base64(JSON_String)
// Note: This string below is a truncated example for illustration
X-Payment: eyJ4NDAyVmVyc2lvbiI6MSwic2NoZW1lIjoiZXhhY3QiLCJuZXR3b3JrIjoi...

Consuming the Response

🔌 API Endpoints

If you paid for an API call, the response will be the actual API data served by the origin.
// 200 OK
{
  "result": "Analysis complete",
  "confidence": 0.98,
  "data": { ... }
}

📦 Digital Products

If you paid for a Product (Digital Good), the response will contain specific access fields.
// 200 OK
{
  "product": {
     "id": "...",
     "name": "Ebook.pdf"
  },
  "content": "https://download-link..."
}