WDK API REFERENCE

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

Asset / Auth Capability Matrix

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

Asset Chain authType Notes
USDT0 Arbitrum One (42161) eip3009 Preferred path. Validate contract version — use WDK adapter.
USDT0 Base (8453) eip3009 Supported. Verify USDT0 contract deployment on Base.
Legacy USDT Any EVM N/A No EIP-3009. Bridge to USDT0 or switch to USDC.
USDC Base (8453) eip3009 Baseline. 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

{
  "invoiceId": "inv_123",
  "walletAddress": "0xYourWalletAddress",
  "sourceAssets": ["USDT0", "USDT", "USDC"],
  "constraints": {
    "maxFeeBps": 75,
    "maxLatencyMs": 12000
  }
}

Request field reference

Field Type Required Description
invoiceId string Yes Your internal invoice or payment reference ID. Used for idempotency.
walletAddress string Yes EVM wallet address that will sign the authorization.
sourceAssets string[] Yes Ordered preference: ["USDT0", "USDT", "USDC"]. P402 selects the first available.
constraints.maxFeeBps number No Maximum total fee in basis points. Routes exceeding this are excluded.
constraints.maxLatencyMs number No Maximum 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

{
  "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

Field Type Required Description
quoteId string Yes From the quote response. Must not be expired.
routeId string Yes The specific route from the quote you want to use.
client object Yes {"type": "wdk", "version": "1.0.0"} — identifies the signer client.
authType "eip3009" "receipt" Yes
amount string Yes Settlement amount in human-readable format: "1.00"
asset "USDT0" "USDC" Yes
payment.scheme "exact" Yes Always "exact" for WDK flows.
payment.authorization object Yes (eip3009) The EIP-3009 authorization fields: from, to, value, validAfter, validBefore, nonce.
payment.signature string Yes (eip3009) EIP-712 signature over the authorization, produced by the WDK signer.
receipt_id string Yes (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/settle authType: 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"
}