Payment verification#

Verify an x402 protocol payment with a specific scheme and network.

Request address#

POST https://web3.okx.com/api/v6/x402/verify

Request parameters#

Parameter	Type	Required	Description
x402Version	String	Yes	Version of the x402 protocol (e.g., 1)
chainIndex	String	Yes	Unique identifier of the blockchain
paymentPayload	Object	Yes	The x402 payment payload carried by the client with the protected request
>x402Version	String	Yes	Version of the x402 protocol (e.g., 1)
>scheme	String	Yes	Settlement scheme, e.g., exact (one‑time fixed‑amount payment)
>payload	Object	Yes	Object containing payment signature and authorization data
>>signature	String	Yes	Cryptographic signature
>>authorization	Object	Yes	Authorization information
>>>from	String	Yes	Payer address
>>>to	String	Yes	Payee address
>>>value	String	Yes	Payment amount (in smallest unit, with precision)
>>>validAfter	String	No	Effective time (Unix timestamp)
>>>validBefore	String	No	Expiration time (Unix timestamp)
>>>nonce	String	Yes	Random nonce to prevent replay attacks
paymentRequirements	Object	Yes	Information describing what resource the payment grants access to (amount, network, asset, payee, etc.)
>scheme	String	Yes	Defines how the payment is settled, e.g., exact (one‑time fixed‑amount payment)
>resource	String	No	Server URL of the resource
>description	String	No	Description of the resource API endpoint
>mimeType	String	No	MIME type of the resource provider’s response
>maxAmountRequired	String	Yes	Maximum payable amount (in smallest unit, with precision)
>maxTimeoutSeconds	Integer	No	Maximum waiting time (in seconds) after authorization becomes valid
>payTo	String	Yes	Payee address
>asset	String	No	Asset identifier or contract address (depending on the network)
>outputSchema	Object	No	Optional parameter specifying the expected JSON structure of the returned resource data
>extra	Object	No	Optional additional parameters, e.g., gasLimit

Response parameters#

Parameter	Type	Description
isValid	Boolean	Whether the payment is valid (true = valid, false = invalid)
payer	String	Address of the payer
invalidReason	String	Reason for invalidation (e.g., insufficient_funds, invalid_network, etc.)

Payment settlement

Error code

Request example#

curl --request POST \
  --url https://web3.okx.com/api/v6/x402/verify \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "x402Version": 1,
  "paymentPayload": {
    "x402Version": 1,
    "scheme": "exact",
    "chainIndex": "196",
    "payload": {
      "signature": "0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee6037b8cc5d04a71a4462f13480",
      "authorization": {
        "from": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
        "to": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
        "value": "1000000000000000000",
        "validAfter": "1716150000",
        "validBefore": "1716150000",
        "nonce": "0x1234567890abcdef1234567890abcdef12345678"
      }
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "chainIndex": "196",
    "maxAmountRequired": "1000000",
    "resource": "https://api.example.com/premium/resource/123",
    "description": "Premium API access for data analysis",
    "mimeType": "application/json",
    "outputSchema": {
      "data": "string"
    },
    "payTo": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "maxTimeoutSeconds": 10,
    "asset": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "extra": {
      "gasLimit": "1000000"
    }
  }
}'

Response example#

200

{
    "code": "0",
    "msg": "success",
    "data": [
        {
            "isValid": true,
            "invalidReason": null,
            "payer": "0xcb30ed083ad246b126a3aa1f414b44346e83e67d"
        }
    ]
}

Payment settlement

Error code