Withdrawals

Withdrawals enable you to send cryptocurrency from your platform to external addresses with built-in multi-signature approval workflows. On this page, we'll dive into the different withdrawal endpoints you can use to create, list, and cancel withdrawals programmatically.

The withdrawal model

The withdrawal model contains all the information about outgoing cryptocurrency payments, including the recipient address, amount, approval status, and transaction details.

Properties

Name
id
Type
string
Description
Unique identifier for the withdrawal.
Name
orgId
Type
string
Description
The organization ID that owns this withdrawal.
Name
chainId
Type
string
Description
The blockchain network in CAIP-2 format (e.g., eip155:1).
Name
tokenId
Type
string
Description
The token identifier in CAIP-19 format.
Name
amount
Type
string
Description
The withdrawal amount in base units (e.g., "50000000" = 50 USDC with 6 decimals).
Name
recipient
Type
string
Description
The destination blockchain address.
Name
memo
Type
string
Description
Optional memo or destination tag (used for XRP, etc.).
Name
reference
Type
string
Description
Unique idempotency key to prevent duplicate withdrawals.
Name
internalNote
Type
string
Description
Internal note for record keeping (not sent on-chain).
Name
status
Type
string
Description
Withdrawal status: Pending, PendingApproval, Processing, Completed, Failed, or Cancelled.
Name
txnHash
Type
string
Description
The transaction hash once the withdrawal is processed on-chain.
Name
txnError
Type
string
Description
Error message if the withdrawal failed.
Name
initiator
Type
string
Description
User ID who created the withdrawal.
Name
approvers
Type
array
Description
Array of user IDs who have approved this withdrawal.
Name
createdAt
Type
timestamp
Description
Timestamp of when the withdrawal was created.
Name
updatedAt
Type
timestamp
Description
Timestamp of when the withdrawal was last updated.

GET/withdrawals

List all withdrawals

This endpoint allows you to retrieve a list of all withdrawals for your organization. You can optionally filter by status.

Query parameters

Name
status
Type
string
Description
Optional. Filter withdrawals by status: PendingApproval, Pending, Processing, Completed, Failed, or Cancelled.

Request

GET

/withdrawals

curl https://api.coinspayd.io/withdrawals \
  -H "x-api-key: {your-api-key}"

Response

{
  "withdrawals": [
    {
      "id": "withdrawal_abc123",
      "orgId": "org_456",
      "chainId": "eip155:1",
      "tokenId": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "amount": "50000000",
      "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
      "memo": "Withdrawal to customer",
      "reference": "ref_12345",
      "internalNote": "Customer payout",
      "status": "Completed",
      "txnHash": "0xabcdef1234567890...",
      "txnError": null,
      "initiator": "user_123",
      "approvers": ["user_123", "user_456"],
      "createdAt": "2025-01-15T11:00:00.000Z",
      "updatedAt": "2025-01-15T11:05:00.000Z"
    }
  ]
}

POST/withdrawals

Create a withdrawal

This endpoint allows you to create a new withdrawal request. Depending on your organization's minWithdrawalSigners setting, the withdrawal may require additional approvals before processing.

Required attributes

Name
chainId
Type
string
Description
The blockchain network in CAIP-2 format.
Name
tokenId
Type
string
Description
The token identifier in CAIP-19 format.
Name
amount
Type
string
Description
Amount in base units (e.g., "50000000" for 50 USDC).
Name
recipient
Type
string
Description
Destination blockchain address.
Name
reference
Type
string
Description
Unique idempotency key to prevent duplicates.

Optional attributes

Name
memo
Type
string
Description
Memo/tag for recipient (required for XRP destination tags).
Name
internalNote
Type
string
Description
Internal note for record keeping.

Request

POST

/withdrawals

curl -X POST https://api.coinspayd.io/withdrawals \
  -H "x-api-key: {your-api-key}" \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": "eip155:1",
    "tokenId": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "amount": "50000000",
    "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
    "reference": "ref_12345",
    "internalNote": "Customer payout"
  }'

Response

{
  "withdrawal": {
    "id": "withdrawal_abc123",
    "orgId": "org_456",
    "chainId": "eip155:1",
    "tokenId": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "amount": "50000000",
    "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
    "memo": null,
    "reference": "ref_12345",
    "internalNote": "Customer payout",
    "status": "Pending",
    "txnHash": null,
    "txnError": null,
    "initiator": "user_123",
    "approvers": ["user_123"],
    "createdAt": "2025-01-15T11:00:00.000Z",
    "updatedAt": "2025-01-15T11:00:00.000Z"
  }
}

GET/withdrawals/:id

Get a withdrawal

Retrieve detailed information about a specific withdrawal by its ID. Useful for checking withdrawal status and transaction details.

Path parameters

Name
id
Type
string
Description
The withdrawal ID.

Request

GET

/withdrawals/:id

curl https://api.coinspayd.io/withdrawals/withdrawal_abc123 \
  -H "x-api-key: {your-api-key}"

Response

{
  "id": "withdrawal_abc123",
  "orgId": "org_456",
  "chainId": "eip155:1",
  "tokenId": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  "amount": "50000000",
  "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
  "memo": "Withdrawal to customer",
  "reference": "ref_12345",
  "internalNote": "Customer payout",
  "status": "Completed",
  "txnHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "txnError": null,
  "initiator": "user_123",
  "approvers": ["user_123", "user_456"],
  "externalUserId": "customer_789",
  "createdAt": "2025-01-15T11:00:00.000Z",
  "updatedAt": "2025-01-15T11:05:00.000Z",
  "Token": {
    "id": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "name": "USD Coin",
    "symbol": "USDC",
    "decimals": 6,
    "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
  }
}

DELETE/withdrawals/:id

Cancel a withdrawal

This endpoint allows you to cancel a pending withdrawal. You can only cancel withdrawals with status Pending or PendingApproval.

Request

DELETE

/withdrawals/withdrawal_abc123

curl -X DELETE https://api.coinspayd.io/withdrawals/withdrawal_abc123 \
  -H "x-api-key: {your-api-key}"

Response

{
  "withdrawal": {
    "id": "withdrawal_abc123",
    "status": "Cancelled",
    "txnError": "CANCELLED BY user_123",
    "updatedAt": "2025-01-15T11:10:00.000Z"
  }
}

Withdrawal status flow

Understanding the withdrawal status progression:

Single Signer (minWithdrawalSigners = 1)

Pending → Processing → Completed/Failed

The withdrawal is automatically processed after creation.

Multi-Signature (minWithdrawalSigners > 1)

PendingApproval → Pending → Processing → Completed/Failed

The withdrawal requires additional approvals before processing.

Cancellation

Withdrawals can be cancelled when in:

Pending status
PendingApproval status

Once a withdrawal enters Processing status, it cannot be cancelled.

Common errors

Error Code	Description
`INVALID_CHAIN`	Chain ID not found or invalid
`INVALID_TOKEN`	Token ID not found
`INVALID_TOKEN_CHAIN`	Token doesn't belong to the specified chain
`INVALID_AMOUNT`	Amount must be greater than 0
`INVALID_RECIPIENT_ADDRESS`	Address format is invalid for the chain
`DUPLICATE_REFERENCE`	Reference key already used for another withdrawal
`WITHDRAWAL_NOT_FOUND`	Withdrawal ID doesn't exist
`WITHDRAWAL_NOT_PENDING`	Can only cancel Pending or PendingApproval withdrawals

XRP withdrawals with memo

For XRP withdrawals that require a destination tag, use the memo field:

curl -X POST https://api.coinspayd.io/withdrawals \
  -H "x-api-key: {your-api-key}" \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": "xrpl:mainnet",
    "tokenId": "xrpl:mainnet/slip44:144",
    "amount": "20000000",
    "recipient": "rN7n7otQDd6FczFgLdlqtyMVrn3HMtthca",
    "memo": "12345",
    "reference": "ref_xrp_001"
  }'