---
title: "Create wallet"
method: POST
path: "/ledger/v2/wallets"
tags: ["Wallets"]
---

# Create wallet

`POST /ledger/v2/wallets`

## Request

- Base URL: `https://api.sandbox.bvnk.com`
- URL: `https://api.sandbox.bvnk.com/ledger/v2/wallets`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/docs/ledger/v2/wallets/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a crypto or fiat wallet associated with a wallet profile. You can create wallets for yourself or for your customers.

To create a self-custody wallet for a customer, set `profileId` to a self-custody wallet profile and specify the `network`. Each request creates one wallet for one currency on one network. For the end-to-end flow, see [Set up self-custody wallets](/bvnk/get-started/self-custody/sc-wallets/).

## Headers

- `Idempotency-Key` string, uuid, required

## Request body

- LedgerWalletV2CreateRequest
  - `customerId` string, uuid: Unique identifier for the customer. **Required if you create a wallet for your customer**.
  - `currency` string, required: Currency code for the wallet.
  - `name` string, required: Display name for the wallet.
  - `profileId` string: ID of the wallet profile to associate. To get the full list of available wallet profiles, see [Get Wallet Profiles](/bvnk/api-explorer/endpoints/wallet-profiles-2). Required for fiat and self-custody wallets. For a self-custody wallet, use a profile with an `id` in the `crypto:self-custodial:<id>` format.
  - `network` 'TRON' | 'ETHEREUM' | 'LITECOIN' | 'BITCOIN' | 'RIPPLE' | 'DOGECOIN' | 'SOLANA' | 'ALGORAND' | 'CARDANO' | 'BINANCE' | 'POLYGON' | 'BITCOIN_CASH' | 'ARC' | 'ARBITRUM' | 'BASE': Blockchain network.

## Response `201`

Wallet created successfully.

- LedgerWalletV2Response
  - `id` string, required: The wallet identifier.
  - `name` string, required: Display name of the wallet.
  - `customer` LedgerWalletV2Customer: Customer with which this wallet is associated. Shown only for customer wallets.
    - `id` string, uuid: Unique identifier for the customer.
    - `name` string: Display name for the customer.
  - `status` 'ACTIVE' | 'INACTIVE' | 'TERMINATED', required: Status of the wallet.
  - `balance` object: Available balance for the wallet.
    - `amount` number, required: Balance amount as a decimal string for fixed precision.
    - `currency` string, required: Wallet currency code.
  - `paymentInstruments` union[]: Payment instruments associated with the wallet. Fiat wallets return bank account details, and self-custody wallets return the blockchain address on the wallet's network. Custodial crypto wallets return an empty array.
    - union
      - LedgerWalletV2FiatLedger: Information about the fiat payment instruments. When a payment reference is required for inbound payments, `remittanceInformationPrefix` indicates the required prefix (e.g. for SWIFT).
        - `type` 'FIAT', required: Type of ledger, must be FIAT for this schema.
        - `accountHolderName` string, required: Name of the account holder.
        - `accountHolderAddress` LedgerWalletV2BankAddress: Physical address of the bank.
          - `addressLine1` string: Primary street address line.
          - `addressLine2` string: Secondary address line (suite, floor, building, etc.).
          - `city` string: City of the bank address.
          - `country` string: ISO 3166-1 alpha-2 country code of the bank address.
          - `stateCode` string: ISO 3166-2 state or province code.
          - `postCode` string: Postal or ZIP code of the bank address.
          - `fullAddress` string: Full formatted address string.
        - `accountNumber` string, required: Account number. Must be provided only if `type` = `FIAT`.
        - `remittanceInformationPrefix` string: Prefix that must appear within the payment reference when a `reference` is required for this rail, for example, SWIFT.
        - `bankDetails` LedgerWalletV2Bank: Bank details associated with the fiat payment instrument.
          - `name` string, required: Name of the bank.
          - `address` LedgerWalletV2BankAddress: Physical address of the bank.
            - `addressLine1` string: Primary street address line.
            - `addressLine2` string: Secondary address line (suite, floor, building, etc.).
            - `city` string: City of the bank address.
            - `country` string: ISO 3166-1 alpha-2 country code of the bank address.
            - `stateCode` string: ISO 3166-2 state or province code.
            - `postCode` string: Postal or ZIP code of the bank address.
            - `fullAddress` string: Full formatted address string.
          - `bic` string, required: Bank Identifier Code (SWIFT/BIC).
          - `nid` LedgerWalletV2BankNid: National identifier for the bank. Present when a local clearing code applies.
            - `value` string, required: The national identifier value (e.g. routing number, sort code).
            - `type` 'ROUTING_NUMBER' | 'SORT_CODE' | 'OTHER': Type of the national identifier.
      - LedgerWalletV2CryptoLedger: Blockchain address of a self-custody wallet. Each self-custody wallet has one address on one network.
        - `address` string, required: Blockchain address to receive funds on the wallet's network.
        - `network` 'TRON' | 'ETHEREUM' | 'LITECOIN' | 'BITCOIN' | 'RIPPLE' | 'DOGECOIN' | 'SOLANA' | 'ALGORAND' | 'CARDANO' | 'BINANCE' | 'POLYGON' | 'BITCOIN_CASH' | 'ARC' | 'ARBITRUM' | 'BASE', required: Blockchain network.
        - `tag` string, nullable: Tag or memo for the address, if the network requires one.
  - `createdAt` string, date-time: Timestamp when the wallet was created in ISO 8601 format.
  - `updatedAt` string, date-time: Timestamp of the most recent update to the wallet in ISO 8601 format.

## Other responses

- `400`: Bad request.
- `401`: Authentication required.
- `403`: Forbidden.
- `409`: Idempotency conflict — a request with this idempotency key is already in flight.
- `422`: Idempotency key reuse — the same key was previously used with a different request payload.
- `429`: Rate limited — too many requests.

## Changes

- **2026-11-06** `c386d436bf2c`: 2 breaking, 15 warning, 2 info
  - the response property `paymentInstruments/items/oneOf[subschema #2: Crypto payment instruments]/tag` became nullable for the status `201`
  - removed the required property `paymentInstruments/items/oneOf[subschema #2: Crypto payment instruments]/type` from the response with the `201` status
  - added the new `ALGORAND` enum value to the `paymentInstruments/items/oneOf[subschema #2: Crypto payment instruments]/network` response property for the response status `201`
  - added the new `ARBITRUM` enum value to the `paymentInstruments/items/oneOf[subschema #2: Crypto payment instruments]/network` response property for the response status `201`
  - …15 more
- **2026-06-16** `97d6c0d2fe2e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/changes/ledger/v2/wallets/post.md)

---

[API](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints.md) - [All operations](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/llms.txt) - [OpenAPI document](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/revisions/c386d436bf2c?raw)