Withdrawals

Create a withdrawal

POST/v1/withdrawals

Snapshots the Payday wallet's USDC on every network into legs towards one destination. Nothing moves until each leg is signed.

API key · or dashboard session.

Request

Shell
curl -fsS "$API/v1/withdrawals" \
  -H "Authorization: Bearer $PAYDAY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "destination": { "chain_id": "8453", "address": "0x1111111111111111111111111111111111111111" } }'

Response

201 Created
{
  "id": "wd_0198f80c-7777-7dc1-a369-90556a64f700",
  "status": "awaiting_signature",
  "wallet_address": "0x1111111111111111111111111111111111111111",
  "destination": {
    "chain": { "id": "8453", "name": "Base", "native_symbol": "ETH" },
    "address": "0x000000000000000000000000000000000000d00d"
  },
  "legs": [
    {
      "id": "wdl_0198f80c-8d2f-7dc1-a369-90556a64f700",
      "kind": "bridge",
      "source_chain": { "id": "143", "name": "Monad", "native_symbol": "MON" },
      "amount": "1.234567",
      "amount_base_units": "1234567",
      "state": "awaiting_signature",
      "authorization": {
        "primary_type": "ReceiveWithAuthorization",
        "typed_data": {
          "domain": {
            "name": "USDC",
            "version": "2",
            "chainId": 143,
            "verifyingContract": "0x754704Bc059F8C67012fEd69BC8A327a5aafb603"
          },
          "primaryType": "ReceiveWithAuthorization",
          "types": {
            "EIP712Domain": [
              { "name": "name", "type": "string" },
              { "name": "version", "type": "string" },
              { "name": "chainId", "type": "uint256" },
              { "name": "verifyingContract", "type": "address" }
            ],
            "ReceiveWithAuthorization": [
              { "name": "from", "type": "address" },
              { "name": "to", "type": "address" },
              { "name": "value", "type": "uint256" },
              { "name": "validAfter", "type": "uint256" },
              { "name": "validBefore", "type": "uint256" },
              { "name": "nonce", "type": "bytes32" }
            ]
          },
          "message": {
            "from": "0x1111111111111111111111111111111111111111",
            "to": "0x2222222222222222222222222222222222222222",
            "value": "1234567",
            "validAfter": "0",
            "validBefore": "1800000000",
            "nonce": "0x18b79105e486e10f626b71939a0226c47316949b7c24ff1c397661ea861fafaa"
          }
        },
        "expires_at": "2027-01-15T08:00:00Z",
        "forwarder": "0x2222222222222222222222222222222222222222",
        "nonce_preimage": {
          "destination_domain": 6,
          "mint_recipient": "0x000000000000000000000000000000000000d00d",
          "salt": "0x0000000000000000000000000000000000000000000000000000000000000007"
        }
      },
      "transfer_tx_hash": null,
      "burn_tx_hash": null,
      "mint_tx_hash": null,
      "failure_reason": null
    },
    {
      "id": "wdl_0198f80c-8888-7dc1-a369-90556a64f700",
      "kind": "transfer",
      "source_chain": { "id": "8453", "name": "Base", "native_symbol": "ETH" },
      "amount": "12.000000",
      "amount_base_units": "12000000",
      "state": "awaiting_signature",
      "authorization": { "primary_type": "TransferWithAuthorization", "typed_data": { "…": "…" }, "expires_at": "2027-01-15T08:00:00Z", "forwarder": null, "nonce_preimage": null },
      "transfer_tx_hash": null,
      "burn_tx_hash": null,
      "mint_tx_hash": null,
      "failure_reason": null
    }
  ],
  "created_at": "2027-01-14T08:00:00Z",
  "completed_at": null,
  "cancelled_at": null,
  "failed_at": null
}

One withdrawal may be open per account. Each leg's authorization.typed_data is the EIP-712 document to sign under that chain's USDC; see Withdrawals for the checklist a signer applies before signing. A reused Idempotency-Key with the same destination replays the withdrawal with Idempotency-Replayed: true; with another destination it is 409 idempotency_conflict.

Headers

Idempotency-Keystringrequired
1–255 bytes.

Body

destination.chain_idstringrequired
Decimal chain id of one of the deployment's networks.
destination.addressstringrequired
Nonzero EVM address you control on that network. Stored EIP-55.

Response

Withdrawal, status awaiting_signature.

idwd_ id
statusstring
awaiting_signature, in_progress, completed, failed, cancelled.
wallet_addressstring
The Payday wallet every leg is signed from.
destination{ chain: Chain, address }
legsLeg[]
One per network holding USDC, in registry order.
legs[].idwdl_ id
legs[].kindtransfer | bridge
Funds already on the destination chain, or crossing through CCTP.
legs[].source_chainChain
legs[].amount, amount_base_unitsstring
The whole balance on that chain.
legs[].statestring
awaiting_signature, authorized, relaying, burned, attested, minting, completed, failed, expired, cancelled.
legs[].authorizationobject | null
While awaiting_signature: primary_type, typed_data (EIP-712, uint256 as decimal strings), expires_at, forwarder and nonce_preimage for bridge legs.
legs[].transfer_tx_hash, burn_tx_hash, mint_tx_hashstring | null
Set as each transaction is finalized.
legs[].failure_reasonstring | null
Set when state is failed.
created_at, completed_at, cancelled_at, failed_attimestamp | null

Status codes

  • 409wallet_not_ready The account has not signed in to the dashboard yet, so its wallet is unknown.
  • 409withdrawal_in_progress Another withdrawal is open; finish or cancel it.
  • 409nothing_to_withdraw No USDC on any network.
  • 503withdrawals_unavailable A balance could not be read, or a chain holding funds cannot bridge on this deployment.