P402 Logo
P402.io
Docs/WDK/API Reference

>_ WDK / REFERENCE

WDK API
REFERENCE.

Complete endpoint contracts for the WDK + USDT0 settlement flow. All requests require Authorization: Bearer <api_key>. Base URL: https://p402.io.

⌘KCommand-palette first navJump:QuickstartAPIErrorsMigrationSecurity

Asset / Auth Capability Matrix

Which authType to use depends on the token and chain. This table shows the supported combinations.

AssetChainauthTypeNotes
USDT0Arbitrum One (42161)eip3009Preferred path. Validate contract version — use WDK adapter.
USDT0Base (8453)eip3009Supported. Verify USDT0 contract deployment on Base.
Legacy USDTAny EVMN/ANo EIP-3009. Bridge to USDT0 or switch to USDC.
USDCBase (8453)eip3009Baseline. No WDK adapter needed — direct EIP-712 signing.
POST/api/v1/liquidity/quote

Preflight route selection. Returns available routes ranked by the constraints you provide. The quoteId is required for the settle call. Quotes expire after 60 seconds.

Request body
Request
{
  "invoiceId": "inv_123",
  "walletAddress": "0xYourWalletAddress",
  "sourceAssets": ["USDT0", "USDT", "USDC"],
  "constraints": {
    "maxFeeBps": 75,
    "maxLatencyMs": 12000
  }
}
Request field reference
FieldTypeRequiredDescription
invoiceIdstringYesYour internal invoice or payment reference ID. Used for idempotency.
walletAddressstringYesEVM wallet address that will sign the authorization.
sourceAssetsstring[]YesOrdered preference: ["USDT0", "USDT", "USDC"]. P402 selects the first available.
constraints.maxFeeBpsnumberNoMaximum total fee in basis points. Routes exceeding this are excluded.
constraints.maxLatencyMsnumberNoMaximum estimated settlement latency in ms. Routes slower than this are excluded.
Response
{
  "quoteId": "q_123",
  "expiresAt": "2026-04-16T12:01:00.000Z",
  "routes": [
    {
      "routeId": "r_fast",
      "sourceAsset": "USDT0",
      "sourceChain": "eip155:42161",
      "destinationChain": "eip155:8453",
      "authType": "eip3009",
      "estimatedFeeBps": 42,
      "estimatedLatencyMs": 3200
    },
    {
      "routeId": "r_usdc",
      "sourceAsset": "USDC",
      "sourceChain": "eip155:8453",
      "destinationChain": "eip155:8453",
      "authType": "eip3009",
      "estimatedFeeBps": 10,
      "estimatedLatencyMs": 1800
    }
  ]
}
POST/api/v1/router/settle

Submit a signed payment intent for settlement. P402 verifies the EIP-712 signature, checks the nonce for replay protection, executes the on-chain transfer (paying gas), and returns a receipt.

Request body
Request
{
  "quoteId": "q_123",
  "routeId": "r_fast",
  "client": { "type": "wdk", "version": "1.0.0" },
  "authType": "eip3009",
  "amount": "1.00",
  "asset": "USDT0",
  "payment": {
    "scheme": "exact",
    "authorization": {
      "from": "0xYourWalletAddress",
      "to": "0xFa772434DCe6ED78831EbC9eeAcbDF42E2A031a6",
      "value": "1000000",
      "validAfter": "1713261540",
      "validBefore": "1713265140",
      "nonce": "0xabc123..."
    },
    "signature": "0x..."
  }
}
Request field reference
FieldTypeRequiredDescription
quoteIdstringYesFrom the quote response. Must not be expired.
routeIdstringYesThe specific route from the quote you want to use.
clientobjectYes{"type": "wdk", "version": "1.0.0"} — identifies the signer client.
authType"eip3009" | "receipt"Yeseip3009 for new signatures; receipt for reusing a prior settlement.
amountstringYesSettlement amount in human-readable format: "1.00"
asset"USDT0" | "USDC"YesThe token being transferred.
payment.scheme"exact"YesAlways "exact" for WDK flows.
payment.authorizationobjectYes (eip3009)The EIP-3009 authorization fields: from, to, value, validAfter, validBefore, nonce.
payment.signaturestringYes (eip3009)EIP-712 signature over the authorization, produced by the WDK signer.
receipt_idstringYes (receipt)Required when authType is "receipt". The receipt_id from a prior settlement.
Response
{
  "settled": true,
  "facilitatorId": "p402-eip3009",
  "receipt": {
    "receipt_id": "rec_abc789",
    "txHash": "0x...",
    "sourceAsset": "USDT0",
    "sourceChain": "eip155:42161",
    "destinationChain": "eip155:8453",
    "amount": "1.00",
    "feeBps": 42,
    "routeId": "r_fast",
    "settled_at": "2026-04-16T12:00:05.000Z"
  }
}

Idempotency

Settlement uses the nonce in the authorization for idempotency. If you retry a request with the same nonce, P402 returns REPLAY_DETECTED (HTTP 409). To retry safely after a network failure without risking double-spend, use the receipt scheme with the receipt_id from the first successful settlement.

POST/api/v1/router/settleauthType: receipt

Reuse a prior settlement receipt. Useful for retrying after a network failure without re-signing, or for proving payment to a service that accepts receipts. Each receipt can only be consumed once.

Request (receipt scheme)
{
  "quoteId": "q_456",
  "routeId": "r_fast",
  "client": { "type": "wdk", "version": "1.0.0" },
  "authType": "receipt",
  "receipt_id": "rec_abc789"
}

Related