Skip to main content
GET
List mandates

Authorizations

Authorization
string
header
required

A JWT signed using your CDP API Key Secret, encoded in base64. Refer to the Generate Bearer Token section of our Authentication docs for information on how to generate your Bearer Token.

Query Parameters

address
string

Filter mandates by the customer's wallet address. A blockchain address. Format varies by network (e.g., 0x-prefixed for EVM, base58 for Solana).

Required string length: 1 - 128
Example:

"0x742d35Cc6634C0532925a3b844Bc454e4438f44e"

network
enum<string>

Filter mandates by the customer's wallet network. Only applies when address is also provided. The blockchain network supported for payment session sources. Testnet networks are only available in sandbox environments.

Available options:
arbitrum,
arbitrum-sepolia,
avalanche,
base,
base-sepolia,
ethereum,
ethereum-sepolia,
optimism,
optimism-sepolia,
polygon,
polygon-amoy,
solana,
solana-devnet
Example:

"base"

status
enum<string>

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. 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.

Available options:
created,
approval_pending,
approval_succeeded,
approval_failed,
revocation_pending,
revocation_succeeded,
revocation_failed,
canceled
Example:

"approval_succeeded"

pageSize
integer
default:20

The number of resources to return per page.

pageToken
string

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

Response

Successfully listed mandates.

mandates
object[]
required

The list of mandates.

nextPageToken
string

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

Example:

"eyJsYXN0X2lkIjogImFiYzEyMyIsICJ0aW1lc3RhbXAiOiAxNzA3ODIzNzAxfQ=="