> This page is for Taurus PRIME.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://taurushq.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://taurushq.ferndocs.com/_mcp/server.

# Custody

# Custody Domain

The custody domain manages crypto addresses (deposit and whitelisted withdrawal addresses) and on-chain transaction visibility.

## Deposit Addresses

Platform-generated addresses for receiving crypto deposits. Each address is specific to a sub-account and instrument.

### Endpoints

| Endpoint                                                                         | Method | Description                   |
| -------------------------------------------------------------------------------- | ------ | ----------------------------- |
| `/addresses/internal/by-sub-account/{subAccountId}`                              | GET    | List deposit addresses        |
| `/addresses/internal/by-sub-account/{subAccountId}/by-instrument/{instrumentId}` | GET    | Get or create deposit address |

### Deposit Address Fields

| Field          | Type   | Description                            |
| -------------- | ------ | -------------------------------------- |
| `address`      | string | Blockchain address                     |
| `instrumentId` | UUID   | Instrument this address receives       |
| `blockchain`   | string | Blockchain network                     |
| `memo`         | string | Tag/memo if required by the blockchain |

## Whitelisted Addresses

Pre-approved external addresses for withdrawals. Addresses must be whitelisted and confirmed before funds can be sent to them.

### Endpoints

| Endpoint                                            | Method | Description                |
| --------------------------------------------------- | ------ | -------------------------- |
| `/addresses/external`                               | POST   | Create whitelisted address |
| `/addresses/external/{id}`                          | PUT    | Update address label       |
| `/addresses/external/init`                          | POST   | Resend confirmation email  |
| `/addresses/external/confirm`                       | POST   | Confirm address with code  |
| `/addresses/external/by-sub-account/{subAccountId}` | GET    | List whitelisted addresses |

### Whitelisted Address Fields

| Field          | Type   | Description                         |
| -------------- | ------ | ----------------------------------- |
| `id`           | UUID   | Address identifier                  |
| `address`      | string | External blockchain address         |
| `label`        | string | User-defined name                   |
| `instrumentId` | UUID   | Instrument for this address         |
| `subAccountId` | UUID   | Sub-account this address belongs to |
| `status`       | enum   | Approval status                     |
| `memo`         | string | Tag/memo if applicable              |

### Address Status

| Status                            | Description                            |
| --------------------------------- | -------------------------------------- |
| `STATUS_CREATED`                  | Address created, awaiting confirmation |
| `STATUS_CONFIRMED`                | User confirmed via email code          |
| `STATUS_PENDING_VERIFICATION`     | Awaiting verification                  |
| `STATUS_VERIFIED`                 | Verified and ready for withdrawals     |
| `STATUS_WHITELISTED_IN_CUSTODIAN` | Whitelisted in custody provider        |

### Confirmation Flow

1. Create address via `POST /addresses/external`
2. Receive confirmation email with code
3. Confirm via `POST /addresses/external/confirm` with code + MFA challenge
4. Address status progresses through verification stages to `STATUS_VERIFIED`

**Cooling Period**: New addresses may require 24-48 hours before becoming active for withdrawals.

## Crypto Transactions

View on-chain transaction details for deposits and withdrawals.

### Endpoints

| Endpoint                    | Method | Description             |
| --------------------------- | ------ | ----------------------- |
| `/crypto-transactions/{id}` | GET    | Get transaction details |

### Transaction Fields

| Field           | Type    | Description                 |
| --------------- | ------- | --------------------------- |
| `id`            | UUID    | Transaction identifier      |
| `txHash`        | string  | Blockchain transaction hash |
| `status`        | enum    | Transaction status          |
| `confirmations` | integer | Current confirmation count  |
| `blockHeight`   | integer | Block number                |

## Custody Holdings

View aggregated custody holdings across the client account.

### Endpoints

| Endpoint                 | Method | Description          |
| ------------------------ | ------ | -------------------- |
| `/custody/holdings/mine` | GET    | Get custody holdings |

### Custody Holding Fields

| Field                         | Type    | Description             |
| ----------------------------- | ------- | ----------------------- |
| `blockchain`                  | string  | Blockchain network      |
| `currency`                    | string  | Currency/token symbol   |
| `address`                     | string  | Custody address         |
| `totalConfirmedBalance`       | decimal | Total confirmed balance |
| `totalUnconfirmedBalance`     | decimal | Pending balance         |
| `availableConfirmedBalance`   | decimal | Available confirmed     |
| `availableUnconfirmedBalance` | decimal | Available pending       |
| `decimals`                    | integer | Decimal precision       |

## Address Formats by Blockchain

| Blockchain | Address Format     | Memo/Tag Required     |
| ---------- | ------------------ | --------------------- |
| Bitcoin    | bc1..., 3..., 1... | No                    |
| Ethereum   | 0x...              | No                    |
| Stellar    | G...               | Yes (memo)            |
| Ripple     | r...               | Yes (destination tag) |

## Security Considerations

1. **Address Verification**: Always verify the full address before sending
2. **Memo/Tag**: Include memo/tag when required or funds may be lost
3. **Network Selection**: Ensure correct blockchain network
4. **Whitelist Period**: New addresses have cooling periods before activation
5. **Test Transactions**: Consider small test transaction first

## Related

* [Use Case: Deposits & Withdrawals](/prime/docs/api-usec-06-deposits-withdrawals)
* [Funding Domain](/prime/docs/api-doma-fund-funding)