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

# Create Virtual Account

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

## Request

- Base URL: `//mapi.boomfi.xyz` (relative, and the document’s source URL is not known)
- URL: `//mapi.boomfi.xyz/partners/accounts/create-virtual-account`
- Auth: one of:
  - API key in header `X-API-KEY`
  - API key in header `X-API-Signature`
  - API key in header `X-API-Nonce`
- TypeScript: <https://skmtc.dev/boomfi/apis/boomfi-merchants-api/docs/partners/accounts/create-virtual-account/post.ts> (a function with typed inputs; its response is checked against the schema)

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.dev/boomfi/apis/boomfi-merchants-api.md) - [All operations](https://skmtc.dev/boomfi/apis/boomfi-merchants-api/llms.txt) - [OpenAPI document](https://skmtc.dev/boomfi/apis/boomfi-merchants-api/revisions/ace3c3df05fe?raw)