Mandates

List mandates

Changed on

Returns a paginated list of mandates that the API key has permission to access. Filter by address (the funding source), network, and status.

get/v2/mandates

Request

  • Base URL: https://api.cdp.coinbase.com/platform
  • URL: https://api.cdp.coinbase.com/platform/v2/mandates
  • Auth: HTTP bearer

Query parameters

addressstring

A blockchain address. Format varies by network (e.g., 0x-prefixed for EVM, base58 for Solana).

Example:0x742d35Cc6634C0532925a3b844Bc454e4438f44e

Filter mandates by the customer's wallet address.

network'arbitrum' | 'arbitrum-sepolia' | 'avalanche' | 'base' | 'base-sepolia' | 'ethereum' | 'ethereum-sepolia' | 'optimism' | 'optimism-sepolia' | 'polygon' | 'polygon-amoy' | 'solana' | 'solana-devnet'

The blockchain network supported for payment session sources. Testnet networks are only available in sandbox environments.

Example:base

Filter mandates by the customer's wallet network. Only applies when address is also provided.

status'created' | 'approval_pending' | 'approval_succeeded' | 'approval_failed' | 'revocation_pending' | 'revocation_succeeded' | 'revocation_failed' | 'canceled'

The most recent action on the mandate. status is an informational indicator of the latest transition; it is not the source of truth for what has durably happened. Read the timestamps for that: approvedAt, canceledAt, and revokedAt each record a durable milestone independently of status.

  • created: the mandate exists but no approval has been attempted. No source attached. Not usable.

  • approval_pending: an approval is in flight. Not usable. Emits acceptance.mandate.approval_initiated.

  • approval_succeeded: the mandate has a source and is usable.

  • approval_failed: the last approval attempt failed. Not usable. Submit a new approval to retry.

  • revocation_pending: a wallet revocation is being confirmed on the network. Emits acceptance.mandate.revocation_initiated. Resolves to revocation_succeeded on success or revocation_failed on failure.

  • revocation_succeeded: a wallet revocation removed the spending allowance on-chain (revokedAt is set). Terminal.

  • revocation_failed: the last wallet revocation attempt did not complete. The spending allowance was not removed, so the mandate remains usable if it was usable before. Submit a new revocation to retry.

  • canceled: the merchant ended the mandate off-chain (canceledAt is set). The on-chain spending allowance may still be live; a later wallet revocation can still move status through the revocation_* values and set revokedAt.

Usable when approvedAt is set, canceledAt is null, revokedAt is null, and expiresAt is null or in the future. Usability is derived from these timestamps, not from status: a failed revocation, for example, leaves status at revocation_failed but the mandate stays usable because the allowance was never removed. Authorization checks the durable conditions in order, and the first match wins: an in-flight approval or revocation returns 409 (mandate_action_pending); revokedAt set returns 422 (mandate_revoked); canceledAt set returns 422 (mandate_canceled); a past expiresAt returns 400 (mandate_expired); any other status returns 422 (mandate_invalid_status). Approve a mandate and get wallet approval options use that same order for the in-flight, revoked, canceled, and expired checks. Any other status except created or approval_failed returns 422 (mandate_invalid_status). Those rejections do not change the timestamps. Debit limits are enforced at authorization time.

Example:approval_succeeded

Filter mandates by their latest action, e.g. approval_succeeded for mandates whose most recent transition was a successful approval. Note that status tracks the latest action, not usability; usability is derived from the approvedAt, canceledAt, and revokedAt timestamps.

pageSizeinteger

The number of resources to return per page.

pageTokenstring

The token for the next page of resources, if any.

Response

Successfully listed mandates.

nextPageTokenstring

The token for the next page of items, if any.

Example response

{
  "mandates": [
    {
      "mandateId": "mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
      "asset": "usdc",
      "source": {
        "address": "0xAbC1234567890aBcDeF1234567890AbCdEf123456",
        "network": "base",
        "asset": "usdc"
      },
      "policy": {
        "maxPerAuthorization": "50.00",
        "maxPerPeriod": {
          "amount": "500.00",
          "period": "month"
        }
      },
      "status": "approval_succeeded",
      "expiresAt": "2027-06-15T12:00:00.000Z",
      "revocationUrl": "https://payments.coinbase.com/mandates/mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad/revoke",
      "approvalRedirect": {
        "failureUrl": "https://merchant.example.com/mandate/approval/failed",
        "successUrl": "https://merchant.example.com/mandate/approval/success"
      },
      "revocationRedirect": {
        "failureUrl": "https://merchant.example.com/mandate/revocation/failed",
        "successUrl": "https://merchant.example.com/mandate/revocation/success"
      },
      "approvedAt": "2025-06-15T12:05:00.000Z",
      "createdAt": "2025-06-15T12:00:00.000Z",
      "updatedAt": "2025-06-15T12:05:00.000Z"
    }
  ],
  "nextPageToken": "eyJsYXN0X2lkIjogImFiYzEyMyIsICJ0aW1lc3RhbXAiOiAxNzA3ODIzNzAxfQ=="
}

Changes