Settle Payment

Submit an x402 payment authorization for on-chain settlement

POST /api/v1/x402/settle

Settle x402 payment authorization

cURL

curl --request POST \
  --url https://api.paratro.com/api/v1/x402/settle \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "x402Version": 1,
  "paymentPayload": {
    "scheme": "exact",
    "network": "base-sepolia",
    "payload": {
      "signature": "0xabc123...",
      "authorization": {
        "from": "0xaaaa...",
        "to": "0xbbbb...",
        "value": "1500000",
        "validAfter": "0",
        "validBefore": "1774601102",
        "nonce": "0xdef456..."
      }
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "base-sepolia",
    "maxAmountRequired": "1500000",
    "resource": "https://example.com/api/resource",
    "description": "API access",
    "mimeType": "application/json",
    "payTo": "0xbbbb...",
    "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
    "maxTimeoutSeconds": 900
  }
}
'

200

{
  "success": false,
  "transaction": "",
  "errorReason": "invalid_payload"
}

Settle Payment

Verify a signed payment authorization and execute on-chain settlement. Supports both exact (fixed amount) and upto (variable amount) schemes.

The request body follows the Coinbase x402 facilitator protocol and is compatible with both V1 and V2 payload formats.

Schemes

exact (default)

The full authorized amount is settled on-chain. This is the standard payment flow.

upto

The payer authorizes a maximum amount, and the server settles only the actual usage. Pass the settlement amount via extra.settlementAmount in the payment requirements:

{
  "x402Version": 2,
  "paymentPayload": {
    "payload": { ... },
    "accepted": {
      "scheme": "upto",
      "network": "eip155:84532",
      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "amount": "1000000",
      "payTo": "0x...",
      "extra": {
        "assetTransferMethod": "permit2",
        "settlementAmount": "30000"
      }
    }
  }
}

Field	Description
amount	Maximum authorized amount (atomic units)
extra.settlementAmount	Actual settlement amount (must be ≤ amount)

Constraints:

• upto only supports Permit2 payload type (ERC-3009 binds value in signature)
• If settlementAmount is "0", no on-chain transaction is executed
• If settlementAmount exceeds amount, the request is rejected

Supported Payload Types

Type	Contract	Chains
ERC-3009 (eip3009)	USDC transferWithAuthorization	All EVM
Permit2 (permit2)	x402ExactPermit2Proxy / x402UptoPermit2Proxy	All EVM
Solana (solana)	SPL Token TransferChecked	Solana

Response

{
  "success": true,
  "transaction": "0xabc123...",
  "payer": "0xdef456...",
  "network": "eip155:84532"
}

Field	Type	Description
success	boolean	Whether settlement succeeded
transaction	string	On-chain transaction hash
errorReason	string	Error description (if success is false)
payer	string	Payer wallet address
network	string	CAIP-2 network identifier

Authorizations

Authorization · string · header · required

JWT access token obtained from the /api/v1/auth/token endpoint.

Body

application/json

x402 payment verification or settlement request.

x402Version · enum<integer> · required

The version of the x402 protocol.

Available options: 1, 2

Example:

1

paymentPayload · object · required

The x402 protocol payment payload that the client attaches to x402-paid API requests to the resource server in the X-PAYMENT header.

Option 1

Option 2

Show child attributes

paymentRequirements · object

The x402 protocol payment requirements that the resource server expects the client's payment payload to meet.

Option 1

Option 2

Show child attributes

Response

200

application/json

Settlement rejected after validation.

Result of settling an x402 payment authorization on-chain.

success · boolean · required

Whether the settlement was successful.

transaction · string · required

Gateway transaction payload field. The current settle implementation returns an empty string.

txId · string

Gateway transaction ID for the settle task.

errorReason · string

Machine-readable reason for settlement failure.

payer · string

Address of the payer.

network · string

Network on which the settlement was executed.