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

# Create and configure subaccounts

> Create end-client subaccounts, configure billing and fees, and manage the subaccount lifecycle.

This section covers:

* What a subaccount is and how it works
* Balance types and transaction types
* Billing and fee configuration
* Integration steps for subaccount creation

***

## What is a subaccount?

A subaccount is an end-client account tied to one or more beneficial owners (e.g., institutional taxable account, joint account, Roth IRA). It represents one account on the ledger.

Each wealth manager has their own ledger instance with two types of subaccounts:

**1. End client funds** — Track end-client positions and transactions.

**2. Anchorage Digital operational funds** — Ensure the ledger remains balanced. Include:

| Operational subaccount           | Purpose                                                                                         |
| :------------------------------- | :---------------------------------------------------------------------------------------------- |
| Network transaction fees for org | Covers on-chain fees. Does not impact end-client ledger balances.                               |
| FBO customer fees for org        | Accrues funds for subaccount and custody fees. Only impacted during the billing cycle.          |
| Payables and receivables for org | Holds funds for settling trades with liquidity providers.                                       |
| Unassigned funds for org         | Holds funds not yet assigned to a subaccount (e.g., in-kind deposits with missing attribution). |

Each end client may have one or many subaccounts assigned to their `customerId`. Funds within a subaccount can be rebalanced across other subaccounts for the same end client, provided they are settled.

***

## Balances

Each subaccount tracks three balance types:

| Balance                  | Description                                                     |
| :----------------------- | :-------------------------------------------------------------- |
| `availableForTrading`    | Balance available to trade — may include unsettled funds.       |
| `availableForWithdrawal` | Settled funds available to withdraw, less any unsettled trades. |
| `totalBalance`           | Balance after all settlements complete.                         |

***

## Subaccount transaction types

| Transaction type | Status values                                                   |
| :--------------- | :-------------------------------------------------------------- |
| `DEPOSIT`        | `PENDING` — queued, funds on hold until `POSTED` or `CANCELED`. |
| `WITHDRAWAL`     | `POSTED` — completed and confirmed on blockchain.               |
| `TRADE`          | `CANCELED` — funds not transferred.                             |
| `MANAGEMENT_FEE` |                                                                 |
| `ADVISORY_FEE`   |                                                                 |
| `MODEL_FEE`      |                                                                 |
| `CUSTODY_FEE`    |                                                                 |

***

## Billing and fee configuration

Plan your billing and fee strategy before onboarding clients.

### Billing methods

| Method            | Description                                                                                       |
| :---------------- | :------------------------------------------------------------------------------------------------ |
| Automated billing | Fees configured at subaccount creation. Billed automatically each cycle.                          |
| Manual billing    | Submitted by the wealth manager via the manual billing API endpoint before the 10th business day. |

### Fee model

| Model                       | Description                                                                                                                                            |
| :-------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bundled                     | Single "management fee" line item on the PC statement. Anchorage Digital's custody fee is deducted from the overall fee charged to the wealth manager. |
| Fully disclosed (unbundled) | Each fee type (custody, management, advisory, model) appears as a separate line item on the PC statement.                                              |

### Fee types

| Fee type         | Details                                                                                                                                                                                                                        |
| :--------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CUSTODY_FEE`    | Configured by Anchorage Digital during wealth manager onboarding. Rate may change based on total AUC per agreed commercial terms. Not configurable via API. Calculated from end-of-day USD value averaged over the fee period. |
| `MANAGEMENT_FEE` | Fee charged by the wealth manager for managing client assets (typically 1–2% of AUM with minimums).                                                                                                                            |
| `ADVISORY_FEE`   | Configured via API at subaccount creation. Used for third-party wealth manager fees; otherwise set to `0`.                                                                                                                     |
| `MODEL_FEE`      | Configured via API at subaccount creation. Used for model fees.                                                                                                                                                                |

### Fee visibility — `isBillable`

| Value               | Behavior                                                                                                                                                                                                                      |
| :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `isBillable: true`  | Fee accrues daily AND is billed to the end-client subaccount monthly. Shows as a separate line item on statements. Fees appear on the 1st of the month. Custody fee defaults to `true` for unbundled billing models.          |
| `isBillable: false` | Fee accrues daily but is NOT billed to the subaccount monthly. Does not appear on statements. Accrued balances are available via API. Useful for tracking internal fee distributions from a single management fee remittance. |

### Fee accruals

Each subaccount includes an `accruedFees` section showing estimated fees based on average AUC — not actual point-in-time fees.

<Note>
  `accruedValue` represents the average fee accrued based on days elapsed and average AUC. It is **not** the actual fees charged based on prior day accruals, and should not be used to display mid-month "performance net of fees" estimates.
</Note>

Key fields in `accruedFees`:

| Field               | Description                                                    |
| :------------------ | :------------------------------------------------------------- |
| `startPeriod`       | Billing month start date.                                      |
| `endPeriod`         | Billing month end date.                                        |
| `accruedValue`      | Accrued fee value to date for the billing period.              |
| `rate`              | Fee rate as a decimal (e.g., `0.01` = 1%).                     |
| `type`              | Fee type corresponding to the `accruedFee` object.             |
| `totalBalanceInUSD` | Most recent AUC balance in USD used to calculate accrued fees. |
| `state`             | `ONGOING` — still accruing. `DONE` — billing period closed.    |

```json Example subaccount with fee accruals theme={null}
{
  "createdAt": "2025-02-01T19:11:06.390Z",
  "customerId": "9bcbbb3136356ff85670085f64cfb4f53419a94277261be0094c4d97de71a4yb",
  "externalSubaccountId": "1A-13579-Doe",
  "fees": [
    { "isBillable": true, "rate": 0, "startDate": "2024-08-02", "type": "ADVISORY" },
    { "isBillable": false, "rate": 0.0025, "startDate": "2024-11-20", "type": "CUSTODY" },
    { "isBillable": true, "rate": 0, "startDate": "2024-08-02", "type": "MANAGEMENT" },
    { "isBillable": true, "rate": 0, "startDate": "2024-08-02", "type": "MODEL" }
  ],
  "name": "1A-13579-Doe",
  "subaccountId": "99fc9d84-4843-4a2c-95cc-1d90385c7955",
  "accruedFees": [
    {
      "accruedValue": "2982.05",
      "endPeriod": "2025-01-31",
      "rate": 0.351,
      "startPeriod": "2025-01-01",
      "state": "DONE",
      "totalBalanceInUSD": "100032.1",
      "type": "CUSTODY"
    },
    {
      "accruedValue": "1731.5",
      "endPeriod": "2025-02-18",
      "rate": 0.351,
      "startPeriod": "2025-02-01",
      "state": "ONGOING",
      "totalBalanceInUSD": "100031.22",
      "type": "ADVISORY"
    }
  ],
  "balances": [
    { "assetType": "BTC", "availableForTrading": "0.00018915", "availableForWithdrawal": "0.00018915", "totalBalance": "0.00032102" },
    { "assetType": "ETH", "availableForTrading": "0.19400093", "availableForWithdrawal": "0", "totalBalance": "0" },
    { "assetType": "USD", "availableForTrading": "87676.46", "availableForWithdrawal": "87676.46", "totalBalance": "100000" }
  ]
}
```

### Fee calculation

<Warning>
  `accruedValue` = (AvgAUC × feeRate) × (numberOfDays / 365)

  Avg AUC is calculated from `totalBalance`. This is an estimate — do not use to calculate performance net of fees.
</Warning>

### Billing lifecycle

1. **Month 1, day 1** — Billing period starts. `accruedFee` begins calculating end of day. `state: ONGOING`.
2. **Month 1, days 2–30** — `accruedFee` reflects daily accrual from day 2.
3. **Month 1, last day** — Billing period closes. `state: DONE`.
4. **Month 2, day 1** — Fee transaction appears on the ledger at 8:00 AM ET as `PENDING`.
5. **Month 2, days 2–9th business day** — Billing dispute period. Contact your account point of contact with any questions.
6. **Month 2, 10th business day** — Billing finalized. Subaccount transaction updates to `POSTED`. Fees withdrawn; wealth manager remittance begins. Updates at 8:00 AM ET.

*Pro-rated fees apply to subaccounts with mid-month start dates.*

### Additional billing considerations

1. **Manual billing** must be submitted via API before the 10th business day.
2. **Cash management** — Keep 3 months of USD in the subaccount to avoid liquidation events that trigger taxable events.
3. **0-rate fees** — No accrual or transaction posted if rate is `0`.
4. **Negative USD balances** — If USD balance goes negative mid-month, it must be offset before the 10th business day.
5. **Rate changes** — Anchorage Digital emails end clients when fees with `isBillable: true` are created or changed.
6. **Fee rate format** — Configure as a decimal: `1% = 0.01`.

### Submitting a manual billing charge

Use manual billing when the wealth manager — not Anchorage Digital's AUC-based accrual — determines what to charge each end client. This applies to `ADVISORY`, `MODEL`, and `MANAGEMENT` fees only. Custody fees are set by Anchorage Digital and are never charged manually.

**`POST /v2/subaccounts/billing/charges`**

| Field                  | Description                                | Required | Type                                    |
| :--------------------- | :----------------------------------------- | :------- | :-------------------------------------- |
| `idempotentId`         | Unique ID to prevent duplicate submissions | Yes      | String                                  |
| `feeType`              | Fee type for this batch                    | Yes      | Enum: `ADVISORY`, `MODEL`, `MANAGEMENT` |
| `interval`             | Billing period this charge covers          | Yes      | Object with `startDate` and `endDate`   |
| `charges`              | Charges to create, up to 100 per request   | Yes      | Array                                   |
| `charges/subaccountId` | Subaccount to charge                       | Yes      | String                                  |
| `charges/amount`       | Amount to charge, in USD                   | Yes      | String                                  |

Each request applies a single `feeType` and `interval` across all charges in the batch — submit separate requests to bill different fee types or periods in the same call.

<CodeGroup>
  ```bash Request theme={null}
  curl --request POST \
       --url https://api.anchorage-staging.com/v2/subaccounts/billing/charges \
       --header 'Api-Access-Key: {API Key}' \
       --header 'accept: application/json' \
       --header 'content-type: application/json' \
       --data '{
    "idempotentId": "b6e1a9b2-5b64-4e6e-9b7a-6b6b6b6b6b6b",
    "feeType": "MANAGEMENT",
    "interval": {
      "startDate": "2025-02-01",
      "endDate": "2025-02-28"
    },
    "charges": [
      { "subaccountId": "cb80459c-a930-444e-8f17-69ba9d0e122f", "amount": "1000.00" }
    ]
  }'
  ```

  ```json Response theme={null}
  {
    "data": {
      "ids": ["9f4b2b3a-1c2d-4e5f-8a9b-0c1d2e3f4a5b"]
    }
  }
  ```
</CodeGroup>

To cancel a charge before it's finalized, use **`DELETE /v2/subaccounts/billing/charges/{chargeId}`** with the ID returned above.

<CodeGroup>
  ```bash Request theme={null}
  curl --request DELETE \
       --url https://api.anchorage-staging.com/v2/subaccounts/billing/charges/9f4b2b3a-1c2d-4e5f-8a9b-0c1d2e3f4a5b \
       --header 'Api-Access-Key: {API Key}' \
       --header 'accept: application/json'
  ```

  ```json Response theme={null}
  {
    "data": {
      "success": true
    }
  }
  ```
</CodeGroup>

<Note>
  Manual charges debit the subaccount immediately and appear on the statement dated the day the charge is submitted — they don't wait for the standard month-end billing cycle. Cancellations and financial impact to Ops and Finance settlement processes are minimal, but a charge can only be canceled before it's finalized.
</Note>

***

## Integration steps: Subaccount creation

### Supported account types

| Account type            | Subtype      | End client(s) | Client type |
| :---------------------- | :----------- | :------------ | :---------- |
| `IRA`                   | —            | 1             | Individual  |
| `IRA`                   | `ROLLOVER`   | 1             | Individual  |
| `IRA`                   | `CONVERSION` | 1             | Individual  |
| `ROTH`                  | —            | 1             | Individual  |
| `ROTH`                  | `ROLLOVER`   | 1             | Individual  |
| `ROTH`                  | `CONVERSION` | 1             | Individual  |
| `JOINT`                 | —            | 2             | Individual  |
| `CUSTODIAL`             | —            | 2             | Individual  |
| `INDIVIDUAL_TAXABLE`    | —            | 1             | Individual  |
| `INSTITUTIONAL_TAXABLE` | —            | 1             | Institution |

<Note>
  Each subaccount requires a signer who can represent the client. The signer can be the end client themselves or another authorized individual.
</Note>

### Expected program signers by account type

| Account type            | Expected program signers                       |
| :---------------------- | :--------------------------------------------- |
| `IRA`                   | Linked end client who owns the subaccount      |
| `ROTH`                  | Linked end client who owns the subaccount      |
| `JOINT`                 | Both linked end clients who own the subaccount |
| `CUSTODIAL`             | Parent end client, not the child               |
| `INDIVIDUAL_TAXABLE`    | Linked end client who owns the subaccount      |
| `INSTITUTIONAL_TAXABLE` | Initial set of named program signers           |

***

### Step 1: Create a subaccount application

**`POST /v2/onboarding/subaccounts`**

Key fields:

| Field                                       | Description                 | Required                 | Type    | Restrictions                                                                       |
| :------------------------------------------ | :-------------------------- | :----------------------- | :------ | :--------------------------------------------------------------------------------- |
| `legalEntityName`                           | Legal entity name           | Yes                      | String  |                                                                                    |
| `accountType`                               | Account type                | Yes                      | Enum    | `IRA`, `ROTH`, `JOINT`, `CUSTODIAL`, `INDIVIDUAL_TAXABLE`, `INSTITUTIONAL_TAXABLE` |
| `accountSubtype`                            | Account subtype             | Only for `IRA` or `ROTH` | Enum    | `ROLLOVER` or `CONVERSION`                                                         |
| `programSignerGroup`                        | List of program signers     | Yes                      | Array   |                                                                                    |
| `programSignerGroup/programSignerFirstName` | First name                  | Yes                      | String  |                                                                                    |
| `programSignerGroup/programSignerLastName`  | Last name                   | Yes                      | String  |                                                                                    |
| `programSignerGroup/programSignerEmail`     | Email                       | Yes                      | String  | Valid email                                                                        |
| `documentPreferenceAddressDefaultEmail`     | Statement delivery email(s) | Yes                      | String  | Comma-separated valid emails                                                       |
| `termsAgreementID`                          | Terms agreement ID          | If T\&Cs enabled         | String  | ID from `/v2/onboarding/agreements/terms`                                          |
| `beneficiaryGroup`                          | Beneficiaries               | No                       | Array   |                                                                                    |
| `beneficiaryGroup/beneficiaryType`          | Type                        | Yes                      | Enum    | `SPOUSE`, `FAMILY_OR_FRIEND`, `CHARITY`, `TRUST`, `ESTATE`                         |
| `beneficiaryGroup/beneficiaryName`          | Name                        | Yes                      | String  |                                                                                    |
| `beneficiaryGroup/beneficiaryAllocation`    | Allocation %                | Yes, must sum to 100     | Number  | 1–100                                                                              |
| `contingencyBeneficiaryGroup`               | Contingency beneficiaries   | No                       | Array   | Same structure as `beneficiaryGroup`                                               |
| `fees`                                      | Fee configuration           | No                       | Array   |                                                                                    |
| `fees/feeType`                              | Fee type                    | Yes                      | Enum    | `ADVISORY`, `MODEL`, `MANAGEMENT`                                                  |
| `fees/feeRate`                              | Fee rate                    | No                       | Number  | Decimal 0–1                                                                        |
| `fees/feeIsBillable`                        | Is fee billable?            | No                       | Boolean |                                                                                    |
| `programCustomers`                          | Linked end clients          | Yes                      | Array   |                                                                                    |
| `programCustomers/programCustomerId`        | End client ID               | Yes                      | String  | `customerId`                                                                       |
| `programCustomers/programCustomerRole`      | Role                        | Yes                      | Enum    | `PRIMARY` or `SECONDARY`                                                           |
| `submit`                                    | Submit immediately          | No, defaults to `false`  | Boolean |                                                                                    |

```json Example request theme={null}
{
  "name": "{{name}}",
  "externalId": "{{externalId}}",
  "submit": true,
  "entries": [
    { "key": "legalEntityName", "value": "SubAccount IRA ROLLOVER" },
    { "key": "accountType", "value": "IRA" },
    { "key": "accountSubtype", "value": "ROLLOVER" },
    { "key": "documentPreferenceAddressDefaultEmail", "value": "kevin.flynn_4@test.com" },
    { "key": "programSignerGroup", "value": [
        { "programSignerFirstName": "Kevin", "programSignerLastName": "Flynn_5", "programSignerEmail": "kevin.flynn_5@test.com" },
        { "programSignerFirstName": "Kevin", "programSignerLastName": "Flynn_6", "programSignerEmail": "kevin.flynn_6@test.com" }
      ]
    },
    { "key": "programCustomers", "value": [
        { "programCustomerId": "{{customerId1}}", "programCustomerRole": "PRIMARY" }
      ]
    },
    { "key": "beneficiaryGroup", "value": [
        { "beneficiaryType": "SPOUSE", "beneficiaryName": "Test beneficiary", "beneficiaryAllocation": "50" },
        { "beneficiaryType": "CHARITY", "beneficiaryName": "Test beneficiary 2", "beneficiaryAllocation": "50" }
      ]
    },
    { "key": "contingencyBeneficiaryGroup", "value": [
        { "beneficiaryType": "FAMILY_OR_FRIEND", "beneficiaryName": "Test beneficiary 3", "beneficiaryAllocation": "25" },
        { "beneficiaryType": "TRUST", "beneficiaryName": "Test beneficiary 4", "beneficiaryAllocation": "75" }
      ]
    },
    { "key": "fees", "value": [
        { "feeType": "ADVISORY", "feeRate": "0.1" },
        { "feeType": "MANAGEMENT", "feeRate": "0.25", "feeIsBillable": true }
      ]
    }
  ]
}
```

A unique `subaccountId` is returned for all future references to this subaccount.

***

### Step 2: List all subaccount applications

**`GET /v2/onboarding/subaccounts`**

Returns all subaccount onboarding applications associated with this API key. Supports `afterId` and `limit` for cursor pagination.

***

### Step 3: Check subaccount application status

**`GET /v2/onboarding/subaccounts/{subaccountId}`**

Errors and missing documents are listed in the `errors` array of the response.

```json Example response theme={null}
{
  "data": {
    "entries": [
      { "key": "programSignerGroup", "value": [
          { "programSignerFirstName": "Kevin", "programSignerLastName": "Flynn_5", "programSignerEmail": "kevin.flynn_5@test.com" },
          { "programSignerFirstName": "Kevin", "programSignerLastName": "Flynn_6", "programSignerEmail": "kevin.flynn_6@test.com" }
        ]
      },
      { "key": "documentPreferenceAddressDefaultEmail", "value": "kevin.flynn_4@test.com" },
      { "key": "accountType", "value": "IRA" },
      { "key": "accountSubtype", "value": "ROLLOVER" },
      { "key": "programCustomers", "value": [
          { "programCustomerId": "43a37de2dcc326579fe9ab3a187c48b786007bd759802dfa04ef1aa35383a273", "programCustomerRole": "PRIMARY" }
        ]
      }
    ],
    "errors": [],
    "externalId": "37c4abc1-b94b-48d7-a41b-c4e4becc865a",
    "name": "SubAccount IRA ROLLOVER 20250407-2",
    "status": "IN_PROGRESS",
    "subaccountId": "4305271f-7c1c-4b72-bb80-82b2e144d19d"
  }
}
```

***

### Step 4: Update the application (if errors are present)

**`PUT /v2/onboarding/subaccounts/{subaccountId}`**

Uses the same `entries` array shape as Step 1. Only include the entries you want to change — omitted fields keep their existing value.

```json Example request theme={null}
{
  "entries": [
    { "key": "documentPreferenceAddressDefaultEmail", "value": "kevin.flynn_4-updated@test.com" }
  ]
}
```

***

### Step 5: Submit the application (if `submit: false`)

**`POST /v2/onboarding/subaccounts/{subaccountId}/submit`**

***

### Step 6: Check subaccount approval status

**`GET /v2/subaccounts/customers/accounts?subaccountIds={subaccountId}`**

Status values: `PENDING` (received, awaiting approval) → `OPEN` (approved and active).

Alternatively, subscribe to the `subaccount.opened` webhook event for async notification.

```json Example response (approved) theme={null}
{
  "data": {
    "applicationId": "6ba46417-66dc-424e-8e68-4fbd2597d993",
    "entries": [
      { "key": "programSignerGroup", "value": [
          { "programSignerFirstName": "Kevin", "programSignerLastName": "Flynn_5", "programSignerEmail": "kevin.flynn_5@test.com" },
          { "programSignerFirstName": "Kevin", "programSignerLastName": "Flynn_6", "programSignerEmail": "kevin.flynn_6@test.com" }
        ]
      },
      { "key": "programCustomers", "value": [
          { "programCustomerId": "43a37de2dcc326579fe9ab3a187c48b786007bd759802dfa04ef1aa35383a273", "programCustomerRole": "PRIMARY" }
        ]
      },
      { "key": "accountSubtype", "value": "ROLLOVER" },
      { "key": "accountType", "value": "IRA" },
      { "key": "beneficiaryGroup", "value": [
          { "beneficiaryAllocation": "50", "beneficiaryName": "Test beneficiary", "beneficiaryRelation": "Primary", "beneficiaryType": "Spouse" },
          { "beneficiaryAllocation": "50", "beneficiaryName": "Test beneficiary 2", "beneficiaryRelation": "Contingency", "beneficiaryType": "Charity" }
        ]
      },
      { "key": "fees", "value": [
          { "feeRate": "0.1", "feeType": "Advisory" },
          { "feeIsBillable": "Yes", "feeRate": "0.25", "feeType": "Management" }
        ]
      },
      { "key": "documentPreferenceAddressDefaultEmail", "value": "gareth.test_3@test.com" },
      { "key": "legalEntityName", "value": "SubAccount IRA ROLLOVER" }
    ],
    "errors": [],
    "status": "COMPLETE"
  }
}
```

***

## Changelog

| Date          | Change                                            |
| :------------ | :------------------------------------------------ |
| June 10, 2025 | Updates for new onboarding API payloads and flows |
| May 1, 2025   | Initial version                                   |