# WDK API REFERENCE

Complete endpoint contracts for the WDK + USDT0 settlement flow. All requests require Authorization: Bearer <api_key>. 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

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

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

```json
{
  "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      | eip3009 for new signatures; receipt for reusing a prior settlement.                          |
| amount                       | string              | Yes      | Settlement amount in human-readable format: "1.00"                                         |
| asset                        | "USDT0" | "USDC"   | Yes      | The token being transferred.                                                                |
| 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

```json
{
  "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)

```json
{
  "quoteId": "q_456",
  "routeId": "r_fast",
  "client": { "type": "wdk", "version": "1.0.0" },
  "authType": "receipt",
  "receipt_id": "rec_abc789"
}
```