---
title: "Create Virtual Account"
method: POST
path: "/partners/accounts/create-virtual-account"
tags: ["Partners"]
---

# Create Virtual Account

`POST /partners/accounts/create-virtual-account`

Create a virtual account with crypto wallets across supported networks. Supports both managed (DFNS) wallets and external (self-custody) wallets via the wallet_address field on chain configurations. Optionally configure deposit splits to automatically route portions of incoming deposits to other virtual accounts.

## Request body

- PartnersCreateVirtualAccountRequest
  - `name` string, required — A descriptive name to identify the account.
  - `reference` string, required — Your own account reference identifier. Must be URL-safe, containing only alphanumeric characters, hyphens, and underscores (no spaces or special characters).
  - `chains` PartnersChainConfig[] — Blockchain configurations for the virtual account. Each entry creates a sub-account on the specified chain. Entries without wallet_address create managed (DFNS) wallets; entries with wallet_address create external (self-custody) sub-accounts.
    - `chain_id` integer — The blockchain network ID.
    - `currencies` string[] — List of currency symbols to enable on this chain.
    - `wallet_address` string — External wallet address for this chain. When provided, creates an external (self-custody) sub-account instead of a managed wallet. Omit for managed (DFNS) wallets.
  - `deposit_splits` PartnersDepositSplitInput[] — Configure automatic splitting of incoming deposits. Each entry routes a percentage of the gross deposit amount to the specified destination account. The remainder (after BoomFi fees and all splits) goes to the virtual account's own external wallet.
    - `account_ref` string — Reference of the target virtual account to receive this split. Exactly one of account_ref or account_id must be provided.
    - `account_id` integer — ID of the target virtual account to receive this split. Exactly one of account_ref or account_id must be provided.
    - `pct` string, required — Percentage of gross deposit amount to route to this destination. Use decimal string (e.g. "2.5" for 2.5%).

## Response `200`

OK

- InternalResponseAccountsOrgSettlementAccountResponse
  - `data` AccountsOrgSettlementAccountResponse
    - `account_number` string — The account number.
    - `account_type` 1 | 2 | 3 — The type of the current account. - 1 = Crypto - 2 = Bank - 3 = Card
    - `address` string — The cryptocurrency wallet address associated with a specific account.
    - `chain` AccountsChainResponse
      - `category` string — The category or classification of the chain.
      - `code` string — The code or abbreviation associated with the chain.
      - `is_testnet` boolean — Indicates whether the chain is a testnet (true) or not (false).
      - `name` string — The name or title associated with the chain.
      - `native_currency_symbol` string — The symbol representing the native currency of the chain.
    - `chain_id` integer — The unique identifier representing a blockchain network or chain.
    - `created_at` string — The timestamp indicating when the entity was created.
    - `created_by` string — Information about the user or entity that created the entry.
    - `currencies` string[] — An array containing the names or symbols of the currencies supported.
    - `deleted_at` string — The timestamp indicating when the account was deleted.
    - `enabled` boolean — Indicates whether the account is currently enabled.
    - `id` integer — The unique identifier for the account.
    - `name` string — The name or title associated with the account.
    - `org_id` string — The identifier representing the organization associated with the account.
    - `properties` object
    - `provider` 1 — The account provider. - 1 = Spreedly
    - `sort_code` string — The sort code associated with the account.
    - `updated_at` string — The timestamp indicating when the entity was last updated.
  - `error` boolean
  - `message` string

## Other responses

- `400` — Bad Request
- `500` — Internal Server Error

---

[API](https://skmtc.net/boomfi/apis/boomfi-merchants-api.md) · [All operations](https://skmtc.net/boomfi/apis/boomfi-merchants-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/boomfi/boomfi-merchants-api/revisions/ace3c3df05fe/schema)