Book Transfers

Learn how to execute fiat and crypto book transfers

Book transfers provide a zero-cost method to move funds between accounts on the Cybrid Platform. The following transfer directions are supported:

• bank -> customer
• customer -> bank
• customer -> customer

All transfers must be like for like. You can transfer:

• fiat -> fiat
• crypto -> crypto

The source and destination accounts must share the same asset type (e.g., USD -> USD, USDC -> USDC).

ℹ️

Pre-funded bank accounts

Book transfers can move funds between a partner's pre-funded bank accounts and customer accounts. For more information about pre-funding, contact partner support.

ℹ️

Side display

Book transfers are always recorded as deposit at the API and raw data level. In the Cybrid portal or custom UIs, the transaction side may appear as withdrawal or deposit depending on the viewer's perspective (e.g., customer vs. bank). This is a display convention, not a data inconsistency. To always show deposit, display the API's side value directly in your frontend logic.

Fiat book transfer

This example transfers $1 USD from a fiat funding bank account to a fiat funding customer account.

1. Create a quote using POST /api/quotes:
   • Set product_type to "book_transfer"
   • Set asset to "USD"
   • Omit side -- all book transfers default to "deposit"
   • Set deliver_amount to 100 (amount in cents)

{
  "product_type": "book_transfer",
  "asset": "USD",
  "deliver_amount": 100
}

ℹ️

deliver_amount vs receive_amount

deliver_amount fixes what you send; fees come out of what the recipient gets. receive_amount fixes what the recipient gets; you pay fees on top. See Create and execute a trade for the canonical explanation.

1. Create a transfer using POST /api/transfers:
   • Set transfer_type to "book"
   • Set quote_guid to the quote GUID from step 1
   • Set source_account_guid to the bank account and destination_account_guid to the customer account
   • Provide source_participants and destination_participants

{
  "transfer_type": "book",
  "quote_guid": "<quote_guid>",
  "source_account_guid": "<bank account_guid>",
  "destination_account_guid": "<customer account_guid>",
  "source_participants": [
    {
      "type": "bank",
      "amount": 100,
      "guid": "<bank_guid>"
    }
  ],
  "destination_participants": [
    {
      "type": "customer",
      "amount": 100,
      "guid": "<customer_guid>"
    }
  ]
}

1. Once the transfer executes, the transferred amount is immediately reflected in the platform_available balance of both the bank and customer accounts.

Crypto book transfer

This example transfers 1 USDC (Ethereum) from a crypto trading bank account to a crypto trading customer account.

1. Create a quote using POST /api/quotes:
   • Set product_type to "book_transfer"
   • Set asset to "USDC"
   • Omit side -- all book transfers default to "deposit"
   • Set deliver_amount to 1000000 (1 USDC in base units)

{
  "product_type": "book_transfer",
  "asset": "USDC",
  "deliver_amount": 1000000
}

1. Create a transfer using POST /api/transfers:
   • Set transfer_type to "book"
   • Set quote_guid to the quote GUID from step 1
   • Set source_account_guid to the bank account and destination_account_guid to the customer account
   • Provide source_participants and destination_participants

{
  "transfer_type": "book",
  "quote_guid": "<quote_guid>",
  "source_account_guid": "<bank account_guid>",
  "destination_account_guid": "<customer account_guid>",
  "source_participants": [
    {
      "type": "bank",
      "amount": 1000000,
      "guid": "<bank_guid>"
    }
  ],
  "destination_participants": [
    {
      "type": "customer",
      "amount": 1000000,
      "guid": "<customer_guid>"
    }
  ]
}

1. Once the transfer executes, the transferred amount is immediately reflected in the platform_available balance of both the bank and customer accounts.

Monitor the transfer

Book transfers settle almost instantly, but all transfers are asynchronous. Confirm the transfer reaches completed before relying on the funds.

Poll GET /api/transfers/{transfer_guid} to check the state, or register for webhooks to receive automatic notifications on state changes.

ℹ️

Sandbox state testing

The expected_state field is available only in sandbox to force specific transfer outcomes. Add "expected_state": "pending" to the transfer request body to exercise state handling. See Sandbox transfers for more.