X402 Payments | Agnic Docs

X402 payment signing and proxying

POST/api/x402/fetch

Transparent X402 Payment Proxy

Fetch any URL with automatic X402 payment handling. If the target URL returns a 402 Payment Required response, AgnicPay automatically signs the payment and retries the request. You get the actual API response back. **This is the recommended endpoint for most use cases.**

Auth:ApiTokenOAuth2

query parameters

Name	Type	Description
url*	string<uri>	Target URL to fetch example: "https://api.example.com/data"
method	"GET" \| "POST" \| "PUT" \| "DELETE" \| "PATCH" default: "GET"	HTTP method to use
maxValue	integer	Maximum payment in atomic units (e.g., 100000 = $0.10 USDC) example: 100000
timeout	integer default: 30000	Request timeout in milliseconds

Request body

Request body to forward to the target URL

object

Example request

{
  "prompt": "Generate a summary"
}

Responses

200Successful response from target URL

object

400Bad request

Field	Type	Description
error	string
error_description	string
message	string

401Unauthorized - invalid or missing authentication

object — circular

402Payment required but exceeded maxValue limit

object — circular

500Internal server error

object — circular

Example (cURL)

curl -X POST 'https://api.agnic.ai/api/x402/fetch?url=https%3A%2F%2Fapi.example.com%2Fdata' \
  -H 'X-Agnic-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"Generate a summary"}'

POST/api/sign-payment

Sign X402 Payment Proof

Sign an X402 payment proof for manual payment handling. Supports both "exact" (EIP-3009 TransferWithAuthorization) and "upto" (EIP-2612 Permit) payment schemes. The easiest approach is to pass the full 402 response from the X402 API directly as the `paymentRequirements` field.

Auth:ApiTokenOAuth2

Request body *

Field

Type

Description

paymentRequirements*

object

Full 402 response from X402 API or manual payment requirements

show nested schema

Field

Type

Description

accepts

object[]

show nested schema

array of

Field	Type	Description
scheme	"exact" \| "upto"
network	"base" \| "base-sepolia" \| "solana" \| "solana-devnet"
maxAmountRequired	string	Amount in atomic units
maxTimeoutSeconds	integer
resource	string<uri>
description	string
mimeType	string
asset	string	USDC contract/mint address
payTo	string	Recipient wallet address
extra	object

requestData*

object

show nested schema

Field	Type	Description
url*	string<uri>
method	string

Example request

{
  "paymentRequirements": {
    "accepts": [
      {
        "scheme": "exact",
        "network": "base-sepolia",
        "maxAmountRequired": "250000",
        "maxTimeoutSeconds": 300,
        "resource": "https://api.example.com/endpoint",
        "description": "Payment for API access",
        "mimeType": "application/json",
        "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
        "payTo": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
        "extra": {
          "name": "USD Coin",
          "version": "2"
        }
      }
    ]
  },
  "requestData": {
    "url": "https://api.example.com/endpoint",
    "method": "POST"
  }
}

Responses

200Payment signed successfully

Field	Type	Description
success	boolean
paymentHeader	string	Base64-encoded X402 payment proof for X-Payment header
paymentProof	object	Decoded payment object for inspection show nested schema object — Decoded payment object for inspection
amountPaid	number	Amount in USD
network	string
userWallet	string
signingWallet	string
scheme	"exact" \| "upto"
paidFromCredit	boolean

400Bad request

Field	Type	Description
error	string
error_description	string
message	string

401Unauthorized - invalid or missing authentication

object — circular

402Payment exceeds spending limits

object — circular

Example (cURL)

curl -X POST 'https://api.agnic.ai/api/sign-payment' \
  -H 'X-Agnic-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"paymentRequirements":{"accepts":[{"scheme":"exact","network":"base-sepolia","maxAmountRequired":"250000","maxTimeoutSeconds":300,"resource":"https://api.example.com/endpoint","description":"Payment for API access","mimeType":"application/json","asset":"0x036CbD53842c5426634e7929541eC2318f3dCF7e","payTo":"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7","extra":{"name":"USD Coin","version":"2"}}]},"requestData":{"url":"https://api.example.com/endpoint","method":"POST"}}'