x402 Protocol Documentation

1. Request a Paid Resource

Make a POST request to the paid endpoint. If you haven't paid, you'll receive a 402 response with payment details.

curl -X POST https://your-domain.com/api/hello

2. 402 Response Schema

The server returns payment instructions in this format:

{
  "chain": "solana",
  "network": "mainnet",
  "asset_mint": "TBA",
  "amount": "10",
  "recipient": "userAddress",
  "reference": "<UNIQUE_REFERENCE_PUBKEY>",
  "expires_at": "<ISO8601_TIMESTAMP>",
  "description": "Access to the hello endpoint result",
  "solana_pay_url": "solana:..."
}

3. Make the Payment

Use the Solana Pay URL to complete payment in your wallet, or construct a transaction manually:

• Send the specified amount of SPL tokens (mint: TBA)
• To the recipient address
• Include the reference public key in the transaction
• Complete before expires_at

4. Verify Payment

Check if your payment has been confirmed:

curl https://your-domain.com/api/verify?reference=<REFERENCE>

# Response when paid:
{
  "paid": true,
  "sig": "<TRANSACTION_SIGNATURE>"
}

# Response when not yet paid:
{
  "paid": false
}

5. Access the Resource

Once payment is verified, make the same POST request again to receive the actual resource:

curl -X POST https://your-domain.com/api/hello

# Response:
{
  "message": "Hello from x402 x402!",
  "paid_reference": "<REFERENCE>"
}