> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bastion.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Crypto transfers and deposits

> How on-chain and off-chain crypto transfers move between Bastion accounts, their status lifecycle, and how deposit webhooks credit recipient balances.

A crypto transfer moves digital assets from one Bastion account to a destination. Transfers operate on Bastion-custodied accounts and are submitted through a single endpoint ([`POST /v2/crypto/transfers`](/v2/api-reference/cryptocurrency-transfers/submit-cryptocurrency-transfer)).

If you're not familiar with how Bastion custody works, start with [Custody concepts](/guides/concepts/custody) before continuing.

## Transfer modes

There are two ways to send crypto from a Bastion account. Which modes are available depends on the account type and where the funds are going.

| Transfer mode | What it does                                                                                                                                    | Destination field                              | Account types                           | Settlement               |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | --------------------------------------- | ------------------------ |
| On-chain      | Sends assets through the blockchain to a wallet address (external wallet, exchange, or Bastion deposit address). Gas fees sponsored by Bastion. | `address_destination` (wallet address + chain) | Segregated or omnibus                   | After block confirmation |
| Off-chain     | Moves assets instantly on Bastion's internal ledger, with no blockchain transaction. No gas fees, no chain selection.                           | `account_destination` (recipient's account ID) | Omnibus to omnibus only (same platform) | Instant                  |

If your platform uses segregated wallets, all transfers are on-chain. If your platform uses omnibus accounts, you can use either mode depending on the destination.

## Asynchronous processing

Crypto transfers are processed asynchronously. Submitting a transfer with [`POST /v2/crypto/transfers`](/v2/api-reference/cryptocurrency-transfers/submit-cryptocurrency-transfer) returns `202 Accepted` with `{ id, request_id }`. The `id` is the transfer identifier, and `request_id` is the idempotency key you supplied. Track the transfer as it moves through Bastion's processing queue by polling [`GET /v2/crypto/transfers/{transfer_id}`](/v2/api-reference/cryptocurrency-transfers/get-cryptocurrency-transfer) with that `id`, or by listening for `submit_cryptocurrency_transfer_v2` webhooks.

A transfer moves through `ACCEPTED` → `SUBMITTED` → `CONFIRMED`, with `FAILED`, `DROPPED`, and `CANCELED` as terminal error states. Each `submit_cryptocurrency_transfer_v2` webhook includes `id`, `request_id`, and `status`. Deduplicate updates on `id` plus `status` and keep your handler idempotent, since deliveries can repeat.

## Deposits

A deposit is the receiving side of a transfer. When crypto arrives at a Bastion account, whether from an external wallet, an exchange, or another account on the same platform, Bastion detects it, runs compliance screening, and credits the recipient's balance.

Deposits are delivered to your platform via `deposit_v2` webhooks. The `source_type` field indicates where the deposit came from:

| Source type | Origin                                              | When it occurs                                               |
| ----------- | --------------------------------------------------- | ------------------------------------------------------------ |
| `ON_CHAIN`  | External wallet or exchange                         | An on-chain transaction is confirmed on the blockchain       |
| `ACCOUNT`   | Another account on the same platform (omnibus only) | An off-chain transfer completes between two omnibus accounts |

Deposits from on-chain transfers include `source_address`, `destination_chain`, and `transaction_hash`. Deposits from off-chain transfers include `source_account_id`, and the chain and hash fields are empty (`CHAIN_UNSPECIFIED`, empty string).

## How transfers and deposits relate

A transfer and a deposit are two sides of the same movement. When a transfer completes, two events fire:

* The **sender** receives a `submit_cryptocurrency_transfer_v2` webhook
* The **recipient** receives a `deposit_v2` webhook

These are separate events on separate accounts. Your platform may handle one or both depending on whether the sender, the recipient, or both are on your platform.

## Transaction limit policies

Platforms can define limits on crypto transfers to manage risk. Transaction limit policies are configured through the Bastion Admin Dashboard and apply to transfers submitted via the crypto transfers endpoint.

Policies are defined by four properties:

| Property          | Description                                                                                                                         |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Scope             | Who the policy applies to: all identities in your app (app-scoped), or a specific identity (identity-scoped)                        |
| Evaluation window | What transactions are considered: the current transaction only (per-transaction), or the cumulative value over the past week        |
| Threshold type    | What happens when the limit is breached: block the transaction and send a webhook (hard), or send a webhook without blocking (soft) |
| Threshold amount  | The minimum amount (in USD) that triggers the policy                                                                                |

Up to four policies may apply to a given identity, one per combination of evaluation window and threshold type. When both an app-scoped and identity-scoped policy exist with the same evaluation window and threshold type, the identity-scoped policy takes precedence.

For full configuration details, see [Transaction limit policies](/v2/api-reference/transaction-limits/overview).

## Related documentation

* **Concepts**

  * [Custody](/guides/concepts/custody)
  * [Identity and account](/guides/concepts/identities-and-accounts)
  * [Supported chains and assets](/guides/concepts/chains-and-assets)

* **Getting started**

  * [Send crypto on-chain](/guides/quickstarts/send-crypto/on-chain)
  * [Send crypto off-chain](/guides/quickstarts/send-crypto/off-chain)
  * [Receive crypto deposits](/guides/quickstarts/receive-crypto-deposits)


## Related topics

- [Receive crypto deposits to a Bastion account](/guides/quickstarts/receive-crypto-deposits.md)
- [Crypto custody](/guides/concepts/custody.md)
- [Send crypto off-chain between omnibus accounts](/guides/quickstarts/send-crypto/off-chain.md)
- [Send crypto on-chain to any wallet address](/guides/quickstarts/send-crypto/on-chain.md)
- [Webhooks API overview](/v2/api-reference/webhooks/overview.md)