X402 E2E Verification and Troubleshooting

X402 involves HTTP, SDK, signatures, Facilitator, and on-chain transactions. When troubleshooting signature or settlement issues, it is recommended to confirm layer by layer in the order of "public entry -> 402 response -> SDK payment handler -> on-chain settlement." This tutorial explains the inspection methods for each layer and lists common errors.

Check Public Entry

Discovery Document:

curl https://platform.acedata.cloud/.well-known/x402

If version and resources are returned, it indicates that the platform discovery document is normal. Note that this address is on platform.acedata.cloud, not api.acedata.cloud.

Facilitator Support Capabilities:

curl https://facilitator.acedata.cloud/supported

If kinds is returned, it indicates that the Facilitator entry is normal.

Check 402 accepts

Send a non-chargeable unauthenticated request:

curl -sS -X POST https://api.acedata.cloud/openai/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "hi"}],
    "max_tokens": 1
  }'

Check if the returned accepts includes the network you want to use:

  • base/exact
  • base/upto
  • skale/exact
  • skale/upto
  • solana/exact

If the target network is not present, it indicates that the API or the current environment is not configured with the corresponding X402 payment method.

Run X402Client Advanced Verification Tool

The X402Client repository provides advanced verification tools that can be used to confirm 402 response selection, signature generation, paid retry, and on-chain settlement. They require a funded wallet, RPC, private key, and development dependencies. For regular business integration, it is recommended to prioritize using TypeScript or Python SDK; only run these tools when needing to locate signature or on-chain settlement issues.

Repository address: https://github.com/AceDataCloud/X402Client

git clone https://github.com/AceDataCloud/X402Client.git
cd X402Client/typescript
npm install
npm install --no-save ethers @solana/spl-token bs58 tsx

Base:

export X402B_BASE_PAYER_PRIVATE_KEY=0x...
TEST_API_PATH='/openai/chat/completions' \
TEST_BODY='{"model":"gpt-4o-mini","messages":[{"role":"user","content":"hi"}],"max_tokens":10}' \
npx tsx scripts/test-real-e2e.ts

SKALE：

export SKALE_BASE_PRIVATE_KEY=0x...
TEST_API_PATH='/openai/chat/completions' \
TEST_BODY='{"model":"gpt-4o-mini","messages":[{"role":"user","content":"hi"}],"max_tokens":10}' \
npx tsx scripts/test-skale-e2e.ts

Solana：

export X402B_SOLANA_PAYER_PRIVATE_KEY=...
npx tsx scripts/test-solana-e2e.ts

The verification tool typically prints:

  1. The 402 response of the first request.
  2. The selected payment requirement.
  3. The signed X-Payment digest.
  4. The HTTP status and response body after retry.
  5. The on-chain settlement transaction, or the reason for failure from the Facilitator.

Do not send private keys or complete X-Payment to the logging system or ticketing system.

Example of public API verification results:

SKALE exact
HTTP 402 -> HTTP 200
content ADC_SKALE_E2E_OK
tx 0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f
block 1969317
explorer https://skale-base-explorer.skalenodes.com/tx/0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f
paid 0.095215 USDC

Base exact
HTTP 402 -> HTTP 200
content ADC_BASE_E2E_OK
tx 0x408430ab3451bc22a51e510cdb4b063d6b9686724fea7a31fc109af20f5cd2f3
block 46726299
explorer https://basescan.org/tx/0x408430ab3451bc22a51e510cdb4b063d6b9686724fea7a31fc109af20f5cd2f3
transfer value 95215 atomic USDC

Solana exact
HTTP 402 -> HTTP 200
content ADC_SOLANA_E2E_OK
chain signature not confirmed in this run because public RPC lookup hit 429

Base upto
HTTP 402 -> HTTP 200
content ADC_BASE_UPTO_OK
tx 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036
block 46726437
explorer https://basescan.org/tx/0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036
signed ceiling 95215 atomic USDC
transfer value 3 atomic USDC

SKALE upto
HTTP 402 -> HTTP 200
content I am Claude Sonnet 4.5, developed by Anthropic.
trace_id ca6f63a9-36b7-434a-b8a1-eb0857475e59
tx 0x51831a97fb97802951bee5dfb36735f4a0b589f153e6a23976fad5495c3925bc
block 1969936
explorer https://skale-base-explorer.skalenodes.com/tx/0x51831a97fb97802951bee5dfb36735f4a0b589f153e6a23976fad5495c3925bc
signed ceiling 4760750 atomic USDC
transfer value 151 atomic USDC

Explanation:

  • SKALE exact, Base exact, Solana exact, Base upto, and SKALE upto have all completed the paid retry from HTTP 402 to HTTP 200.
  • The on-chain transaction for SKALE exact can be found on the SKALE explorer, with a settlement amount of 0.095215 USDC.
  • The on-chain transaction for Base exact can be found on BaseScan, with a settlement amount of 95215 atomic USDC.
  • The signed ceiling for Base upto is 95215 atomic USDC, but the actual on-chain settlement is 3 atomic USDC, indicating that the post-measurement charges are based on actual usage.
  • The signed ceiling for SKALE upto is 4760750 atomic USDC, with the actual on-chain settlement being 151 atomic USDC, and the on-chain transaction can be found on the SKALE explorer.
  • The Solana path has confirmed paid retry and model output. Public RPC may be rate-limited; for strict on-chain reconciliation, please use your own Solana RPC or platform-side settlement records to confirm transaction signatures.

SDK Smoke Test

The advanced verification tools are used to check signatures and on-chain settlements. The business side should also perform an SDK smoke test to confirm that the application code can automatically handle 402 through the payment handler. Below only shows the core snippet; the complete code needs to include wallet, provider, and import.

TypeScript:

const client = new AceDataCloud({
  paymentHandler: createX402PaymentHandler({
    network: 'skale',
    evmProvider,
    evmAddress: wallet.address
  })
});

const res = await client.openai.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Reply with exactly ADC_SDK_X402_OK' }],
  max_tokens: 8
});

Python:

client = AceDataCloud(
    payment_handler=create_x402_payment_handler(
        network="skale",
        evm_signer=signer,
    )
)

res = client.openai.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Reply with exactly ADC_PY_X402_OK"}],
    max_tokens=8,
)

If the model returns the fixed string as requested, it indicates that the SDK, payment handler, Gateway, Facilitator, and upstream API are connected.

The results of the SDK smoke test are as follows:

TypeScript SDK
payer 0xd0479FA9FD8C678303d477433d24C15e3723CC1C
elapsed_ms 6782
content ADC_TS_SDK_X402_OK
id chatcmpl-DlcVLO4PQWvmjPDQpy9yQw2QdLGAT

Python SDK
payer 0xd0479FA9FD8C678303d477433d24C15e3723CC1C
elapsed_ms 4786
content ADC_PY_SDK_X402_OK
id chatcmpl-DlcWajqAHOop3iebmO19XRfT5bTPz

Results explanation:

  • The TypeScript SDK automatically handles 402, signing, and retries through createX402PaymentHandler, ultimately obtaining ADC_TS_SDK_X402_OK.
  • The Python SDK completes the same link through create_x402_payment_handler, ultimately obtaining ADC_PY_SDK_X402_OK.
  • Both smoke tests use the SKALE payer 0xd0479FA9FD8C678303d477433d24C15e3723CC1C.
  • The returned object from the Python SDK is a dict, and the content can be read using res["choices"][0]["message"]["content"] in the example.

Order Payment E2E

Order payment uses the platform API of platform.acedata.cloud, requiring a platform account token. The complete link is: create a Pending order, POST /api/v1/orders/{order_id}/pay/ triggers 402, then retry with X-Payment.

Example of small order payment verification results:

created order 78481793-304e-47f7-bc0c-8231aec9cc1e
created state Pending
created price 1.26

http_status=402
x402Version 1
accepts [('base', 'exact', '1200000'), ('solana', 'exact', '1200000')]

status 200
order state Finished
pay_way X402
pay_id 0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151
settle_header {'success': True, 'network': 'base', 'transaction': '0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151'}

Base tx status 1
block 46726704
explorer https://basescan.org/tx/0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151
transfer value 1200000 atomic USDC

Results explanation:

  • After creating the order, the order status is Pending, and the price is 1.26.
  • The first pay/ request returns HTTP 402, with accepts containing Base exact and Solana exact, both for the amount of 1200000 atomic USDC.
  • After retrying with Base X-Payment, it returns HTTP 200, and the order status changes to Finished, with pay_way being X402.
  • The X-PAYMENT-RESPONSE decoded shows success=True, network=base, and provides the same transaction hash.
  • The transaction status on BaseScan is 1, and the transfer amount is 1200000 atomic USDC, which is 1.2 USDC.
  • The creation price of 1.26 enters the X402 payment process, applying the X402 payment discount, resulting in a final signed and settled amount of 1.2 USDC.

If the order payment does not have Authorization: Bearer {platform_token}, or the order does not belong to the current account, it will fail at the platform permission layer; this is different from directly calling the account-less X402 API of api.acedata.cloud.

Common Errors

Phenomenon Troubleshooting Direction
The first request is not 402 Check if Authorization was mistakenly included, or if this API does not yet have X402 pricing.
No payment requirement for network The target network is not in accepts, switch networks or check Gateway configuration.
invalid_402 The 402 response is not valid JSON, check proxy, gateway, or error page.
Authorization nonce already processed The same X-Payment was reused, re-sign.
invalid_upto_evm_payload_invalid_signature Check if the upto chainId, Permit2 domain, facilitator address, and signing account are consistent.
PERMIT2_ALLOWANCE_REQUIRED Execute approve-permit2 for USDC on the target chain.
Payer has insufficient USDC balance The payment wallet has insufficient USDC.
HTTP 200 but no tx hash The actual amount in upto may be 0, or the settlement record is still being written asynchronously.
Solana Missing transaction payload The X-Payment envelope does not contain a serialized transaction or signature, check the wallet adapter.

SKALE upto Checklist

SKALE upto has completed HTTP paid retry and on-chain settlement verification. Since the upto signature will bind more EVM typed data parameters, it is essential to confirm that the real-time fields in the 402 response are completely consistent with the client signature during integration.

SKALE exact
HTTP 402 -> HTTP 200
content ADC_SKALE_E2E_OK
tx 0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f

SKALE upto
HTTP 402 -> HTTP 200
content I am Claude Sonnet 4.5, developed by Anthropic.
trace_id ca6f63a9-36b7-434a-b8a1-eb0857475e59
approval tx 0x646e92908cc31614bf99f22b13f48a00a74ddd89f7614327ea59802f1094629e
settlement tx 0x51831a97fb97802951bee5dfb36735f4a0b589f153e6a23976fad5495c3925bc
explorer https://skale-base-explorer.skalenodes.com/tx/0x51831a97fb97802951bee5dfb36735f4a0b589f153e6a23976fad5495c3925bc
signed ceiling 4760750 atomic USDC
settlement value 151 atomic USDC

If SKALE upto returns invalid_upto_evm_payload_invalid_signature, prioritize checking:

  1. The extra.chainId returned by the API for skale/upto.
  2. The extra.facilitatorAddress returned by the API.
  3. The SKALE upto facilitator address returned by https://facilitator.acedata.cloud/supported.
  4. Permit2 domain, spender, USDC contract, and signing account.
  5. Whether the wallet has already approved Permit2 for SKALE USDC.

The signature digest of upto simultaneously binds the Permit2 domain, chain ID, spender, recipient address, facilitator address, and validAfter. If any of these items are inconsistent, the Facilitator will recover the erroneous signer, thus returning an invalid signature. If all these are consistent but it still returns 402, the next step is to check the Permit2 allowance; if unauthorized, it will return PERMIT2_ALLOWANCE_REQUIRED.

Save Verification Information

A complete verification should save at least:

  • API path and request body summary;
  • Selected network and scheme;
  • maxAmountRequired;
  • Payer wallet address;
  • Final HTTP status;
  • Model output or task ID in the response;
  • Settlement transaction link;
  • Gateway trace ID or platform usage record ID.

Do not save private keys, complete X-Payment, complete EIP-712 signature, or mnemonic phrases.