Performing Token Transfers

Organizational Custody allows your application to move assets directly from a wallet set using your API key. This guide covers how to transfer native blockchain assets (e.g., ETH, SOL) and fungible tokens (e.g., USDC, USDT).

1. Prerequisites

• MPC Mode: If your organization is in Trustless MPC mode, you must provide your encryptedOrganizationSecret with each transfer request.
• Token IDs: Ensure you have the correct Planbok tokenId for the asset you wish to send. You can find these via the GET /v2/tokens endpoint.

2. Initiating a Transfer

Use a single API call to broadcast a transfer to the blockchain.

Endpoint: POST /v2/organization/transactions/transfer
Headers:

• PLANBOK-X-API-KEY: <your_api_key>

Request Body (Standard MPC):

Code
{
  "idempotencyKey": "a9883653-e570-4f53-874e-5e7e0e0fb23e",
  "walletId": "69a5380b969f8c8adc76af56",
  "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "tokenId": "69a2f6c2a80a22691f80f86f",
  "amounts": ["0.1"]
}

Request Body (Trustless MPC):

Code
{
  "idempotencyKey": "a9883653-e570-4f53-874e-5e7e0e0fb23e",
  "walletId": "69a5380b969f8c8adc76af56",
  "destinationAddress": "0x...",
  "tokenId": "...",
  "amounts": ["0.1"],
  "encryptedOrganizationSecret": "BASE64_CIPHERTEXT_HERE"
}

• idempotencyKey: A unique UUID v4 to prevent double-spending on retries.
• amounts: An array of strings. Most transfers use a single amount, but some chains/scenarios support multi-recipient outputs.

3. Handling the Response

The API returns a transactionId and, once broadcast, the transactionHash.

Response Example:

Code
{
  "success": true,
  "data": {
    "id": "bc5738bc...",
    "transactionHash": "0x0b4207ac...",
    "status": "pending"
  }
}

4. Multi-Chain Considerations

• EVM: Gas fees are automatically estimated and handled by the MPC nodes.
• Solana: The system automatically handles Associated Token Account (ATA) creation if the recipient doesn't have one for the specific token.
• Bitcoin: The system manages UTXO selection and change address derivation automatically.

Next Steps

For interacting with smart contracts beyond simple transfers, see the Smart Contract Interactions guide.