Sign in
Mandates

Approve a mandate with a wallet

Changed on

Customer-initiated. Approves a mandate on a wallet source using the customer's signed payloads from Get wallet approval options. The customer signs the payloads themselves, so this call is unauthenticated. The mandate must be in created or approval_failed status, not expired, and have no approval or revocation in flight.

Returns a pending approval and moves the mandate to approval_pending. On success the mandate's source is set and status becomes approval_succeeded; it can then be used by Authorize a payment session with a mandate. On failure status becomes approval_failed and a new approval can be submitted. Follow progress with Get a mandate approval or the acceptance.mandate.approval_* webhooks.

post/v2/mandates/{mandateId}/approvals/wallet

Request

  • Base URL: https://api.cdp.coinbase.com/platform
  • URL: https://api.cdp.coinbase.com/platform/v2/mandates/{mandateId}/approvals/wallet
  • Auth: HTTP none

Path parameters

mandateIdstring required

The ID of the mandate, a UUID prefixed by mandate_.

Example:mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad

The unique identifier of the mandate to approve.

Headers

X-Idempotency-Keystring

An optional string request header for making requests safely retryable. When included, duplicate requests with the same key will return identical responses. Refer to our Idempotency docs for more information on using idempotency keys.

Request body

optionIdstring required

The identifier of the chosen option. Must match an optionId from the Get wallet approval options response.

metadataMetadata

Optional metadata as key-value pairs. Use this to store additional structured information on a resource, such as customer IDs, order references, or any application-specific data. Up to 10 key/value pairs may be provided. Keys and values are both strings. Keys must be ≤ 40 characters; values must be ≤ 500 characters.

Example request

{
  "optionId": "opt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "signedPayloads": [
    {
      "payloadId": "payload_af2937b0-9846-4fe7-bfe9-ccc22d935114",
      "signature": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab"
    }
  ]
}

Response

Successfully created mandate wallet approval.

approvalIdstring required

The ID of an approval, a UUID prefixed by approval_.

status'pending' | 'succeeded' | 'failed' required

The status of an approval attempt:

  • pending: the submitted source is being bound and verified.

  • succeeded: the mandate's source is attached and its status becomes approval_succeeded.

  • failed: the attempt could not be completed (see error). The mandate's status becomes approval_failed; submit a new approval to retry (which moves it back to approval_pending).

metadataMetadata

Optional metadata as key-value pairs. Use this to store additional structured information on a resource, such as customer IDs, order references, or any application-specific data. Up to 10 key/value pairs may be provided. Keys and values are both strings. Keys must be ≤ 40 characters; values must be ≤ 500 characters.

createdAtstring date-time required

The UTC ISO 8601 timestamp at which the approval was created.

updatedAtstring date-time required

The UTC ISO 8601 timestamp at which the approval was last updated.

Example response

{
  "approvalId": "approval_5f0e9d8c-7b6a-4321-fedc-ba0987654321",
  "status": "succeeded",
  "source": {
    "address": "0xAbC1234567890aBcDeF1234567890AbCdEf123456",
    "network": "base",
    "asset": "usdc"
  },
  "onchainTransactions": [
    {
      "transactionHash": "0xabc123def456789012345678901234567890abcdef1234567890abcdef123456",
      "network": "base"
    }
  ],
  "createdAt": "2025-06-15T12:04:00.000Z",
  "updatedAt": "2025-06-15T12:05:00.000Z"
}

Changes