Funding

created → awaiting_funds → detected → bridging → credited
                              ↘         ↘         ↘
                               ╰─────────┴─────────┴──→ failed

A deposit never moves backwards. Legal transitions are enforced in code, and credited and failed are both terminal.

The two guards against a double credit

• The source transaction hash is unique. One on-chain transaction funds one deposit, ever.
• The ledger entry's idempotency key is derived from the deposit id, so a second credit attempt collides with the ledger's own uniqueness index.

The list is fetched live on every call rather than cached. A cached copy would be a list of routes we believe exist, and the first delisting would hand a player an address that eats their funds. That is also why an upstream outage returns 502 bridge_unavailable rather than a stale list.

{
  "retrievedAt": "2026-08-20T17:04:11.902Z",
  "count": 1,
  "assets": [
    {
      "symbol": "USDC",
      "name": "USD Coin",
      "chainId": "137",
      "network": "Polygon",
      "tokenAddress": "0x…",
      "decimals": 6,
      "minimumUsd": 5,
      "addressKind": "evm"
    }
  ],
  "symbols": ["USDC"],
  "depositsEnabled": true
}

• depositsEnabled is false when no treasury is configured, and depositsDisabledBecause then lists what is missing. Check it before showing a deposit button: the asset list is still returned either way.
• minimumUsd is the route's own minimum, not ours. Below it a transfer will not bridge, and the funds are stranded rather than refunded.
• addressKind is one of evm, svm, btc, tron, and tells you which deposit address shape the route is funded from.
• decimals is required to render an amount. Base units are integers; a display amount is not.

POST /api/v1/funding/deposit-address
Authorization: Bearer pk_test_...
X-Predicta-User: your-own-player-id

{ "asset": "USDC", "chainId": "137" }

{
  "depositId": "…",
  "userId": "your-own-player-id",
  "status": "created",
  "asset": "USDC",
  "chainId": "137",
  "network": "Polygon",
  "depositAddress": "0x…",
  "tokenAddress": "0x…",
  "decimals": 6,
  "minimumUsd": 5,
  "addressKind": "evm",
  "createdAt": "2026-08-20T17:04:12.115Z",
  "pollUrl": "/api/v1/funding/deposits/…"
}

The route is checked against the live catalogue before anything is persisted, so a deposit row can never describe a pair that is not accepted. The row is then written before an address is handed out, because an address a player has already funded and we have no record of is the one failure with no recovery path.

• This is the one funding call that creates an identity. A deposit must name the user it will credit, so a first-time X-Predicta-User is registered here rather than rejected.
• chainId is accepted as a string or a number and is normalised to a string. It is an identifier, not an integer to do arithmetic on.
• Follow pollUrl rather than building the path yourself.

Refusals

{
  "depositId": "…",
  "status": "bridging",
  "providerStatus": "SUBMITTED",
  "eligibleToCredit": false,
  "asset": "USDC",
  "chainId": "137",
  "network": "Polygon",
  "depositAddress": "0x…",
  "minimumUsd": 5,
  "sourceTxHash": "0x…",
  "sourceAmountBaseUnit": "25000000",
  "creditedAmount": null,
  "ledgerEntryId": null,
  "failureReason": null,
  "timeline": {
    "createdAt": "…", "awaitingFundsAt": "…", "detectedAt": "…",
    "bridgingAt": "…", "creditedAt": null, "failedAt": null
  },
  "history": [
    { "from": "created", "to": "awaiting_funds", "at": "…" },
    { "from": "awaiting_funds", "to": "detected",  "at": "…" }
  ]
}

• The bridge is polled on every read unless you pass ?sync=false. A non-terminal deposit therefore refreshes itself; a credited or failed one never does.
• If that poll fails, the call still returns 200 with the stored lifecycle and a syncError field. A bridge outage must not blank out a deposit a player is anxiously watching, and a 502 here would read as though the money were gone.
• eligibleToCredit means the transfer has arrived and a credit may now be made. It is not a credit. Only status: "credited" with a ledgerEntryId is that.
• 404 unknown_deposit covers both “no such deposit” and “not yours”, deliberately. A partner must not be able to probe for another's deposit ids by comparing error codes.
• Every transition appends to history rather than overwriting a field, so a deposit's past is inspectable after the fact.