Create wallets
BVNK offers the ability to create and manage both crypto and fiat wallets directly from within the BVNK portal, and via API. You can create wallets for your customers or for yourself. If you create a wallet for a customer, always specify the customer's ID and reference, otherwise the wallet is created for your own account.
Retrieve wallet profiles
Before adding a wallet to your account, you must assign a wallet profile to it. The wallet profile is a template that defines the currency codes and payment methods available for a wallet.
To list the existing wallet profiles, send the GET /ledger/v2/wallets/profiles request. You can filter results with the optional q query parameter using Lucene query syntax, for example currency:USD, method:SWIFT, or customerId:550e8400-e29b-41d4-a716-446655440000 AND currency:USD.
| Query parameter | Description |
|---|---|
q | Optional search and filter expression. You can filter by:
|
In the response, each profile has an id that you pass as a "profileId" when you create a wallet. Available currencies and methods depend on your account and jurisdiction.
- Wallet profiles
- Single profile (excerpt)
{
"content": [
{
"id": "fiat:gbp:abcd1234",
"currencies": ["GBP"],
"methods": ["FASTER_PAYMENT"]
},
{
"id": "fiat:eur:efgh5678",
"currencies": ["EUR"],
"methods": ["SWIFT"]
},
{
"id": "fiat:usd:ijkm9012",
"currencies": ["USD"],
"methods": ["SWIFT"]
},
{
"id": "fiat:usd:nlop3456",
"currencies": ["USD"],
"methods": ["ACH", "FEDWIRE"]
},
{
"id": "fiat:qrst7890",
"currencies": ["EUR"],
"methods": ["SEPA_CT", "SEPA_INST"]
},
{
"id": "crypto:custodial:uvxz1234",
"currencies": [
"USDT",
"PYUSD",
"POL",
"BTC",
"SOL",
"BNB",
"XRP",
"ETH",
"USDC",
"USDG",
"LTC",
"TRX"
],
"methods": []
}
],
"totalPages": 1
}
Create a wallet with a profile
To create a wallet, do the following:
- API
- Portal
To create a fiat or crypto wallet with an assigned wallet profile, send the POST /ledger/v2/wallets request with a JSON body like the following. Use the id from GET /ledger/v2/wallets/profiles as profileId.
- Direct fiat wallet
- Fiat wallet for a customer
- Crypto wallet for a customer
{
"currency": "USD",
"name": "Swift Wallet",
"profileId": "fiat:usd:ijkm9012"
}
| Parameter | Required | Description |
|---|---|---|
customerId | Unique identifier for the customer. Required if you create a wallet for your customer. | |
currency | ✅ | Currency code for the wallet. |
name | ✅ | Display name for the wallet. |
profileId | ✅ | Wallet profile id from GET /ledger/v2/wallets/profiles. |
In the successful response, you get the details of the new wallet:
- Fiat Wallet
- Crypto Wallet
{
"id": "a:26021236770550:llAoATM:1",
"customer": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "My Wallet"
},
"status": "ACTIVE",
"balance": {
"amount": 0,
"currency": "EUR"
},
"ledgers": [],
"capabilities": {
"safeguarded": true,
"currencyType": "FIAT"
}
}
The id of the created wallet is returned in a Location response header, for example https://api.sandbox.bvnk.com/ledger/v2/wallets/{id}.
Wallets are not created immediately: a new wallet often appears as INACTIVE first , from there it automatically transitions to an ACTIVE state. The activation process can take several minutes. Poll GET /ledger/v2/wallets/{id} or use the webhooks rather than creating duplicate wallets if activation is slow.
When the wallet is created, the ledgers array is empty and the balance is 0. The ledgers array will be populated with the details after the wallet is activated and the webhook is received.
The wallet can also have the TERMINATED status. This means the wallet can no longer be used, and that state is final; BVNK can never reactivate it. All operations, including receiving pay-ins, sending payouts, and currency conversions, are blocked for the terminated wallets. You can only access its transaction history. In case of a fiat wallet, the associated virtual account will be permanently closed with the banking partner. To learn how to terminate a wallet, see the Manage wallets guide.
Retrieve wallets
Use the wallet endpoints to monitor status and balances. GET /ledger/v2/wallets returns summaries only and does not include ledgers. Full ledger and account details are returned by GET /ledger/v2/wallets/{id} for a single wallet.
All wallets
To list all wallets, send the GET /ledger/v2/wallets request.
The list response returns wallet summaries without ledgers. For ledgers and full account details, call GET /ledger/v2/wallets/{id} with that wallet's {id}.
Response
{
"content": [
{
"id": "a:25103169967870:RktIDUt:1",
"customer": {
"id": "d9a5465b-1f77-4113-87f7-c8290d2dd178",
"name": "Some Wallet Name"
},
"status": "ACTIVE",
"balance": {
"amount": 9714.04,
"currency": "USD"
},
"capabilities": {
"safeguarded": false,
"currencyType": "FIAT"
}
},
{
"id": "a:25103169967871:Qr7mK2a:1",
"customer": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Acme Treasury"
},
"status": "INACTIVE",
"balance": {
"amount": 1304.0,
"currency": "EUR"
},
"capabilities": {
"safeguarded": true,
"currencyType": "FIAT"
}
},
{
"id": "a:25103169967872:Tm2Lx8p:1",
"customer": {
"id": "4aa1b63f-8db2-4db9-a33e-8dbf7d5aa7d8",
"name": "Northwind Operations"
},
"status": "INACTIVE",
"balance": {
"amount": 0.2571,
"currency": "BTC"
},
"capabilities": {
"safeguarded": false,
"currencyType": "CRYPTO"
}
},
{
"id": "a:25103169967873:Ym9Vn4c:1",
"customer": {
"id": "2b54d745-e0dd-4ea8-97aa-df2cb9dbe203",
"name": "Contoso Retail"
},
"status": "TERMINATED",
"balance": {
"amount": 0.0,
"currency": "USDT"
},
"capabilities": {
"safeguarded": true,
"currencyType": "CRYPTO"
}
}
],
"pageable": {
"pageNumber": 0,
"pageSize": 10
},
"hasNext": false
}
Specific wallet
To retrieve wallet details by its unique identifier, send the GET /ledger/v2/wallets/{id} request with the {id} specified in the path.
In the response, you receive full wallet details, including ledgers:
- Crypto
- Fiat
{
"id": "a:26021236770551:mmBoATM:1",
"customer": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "My Wallet"
},
"status": "ACTIVE",
"balance": {
"amount": "100.00",
"currency": "BTC"
},
"ledgers": [
{
"type": "CRYPTO",
"address": "tb1qk56vqrp9pzesjwf599mlqwzc7a6scwgq3y2ee6",
"network": "BTC"
}
],
"capabilities": {
"safeguarded": false,
"currencyType": "CRYPTO"
}
}
Customer's wallets
To retrieve wallets for a specific customer, send the GET /ledger/v2/wallets request and filter by customer ID using q and the Lucene syntax, for example:
GET /ledger/v2/wallets?q=customerId:550e8400-e29b-41d4-a716-446655440000 AND status:ACTIVE
The above request returns all active wallets for your customer with ID 550e8400-e29b-41d4-a716-446655440000.
In the response, you receive the list with detailed information on each customer wallet:
Response
{
"content": [
{
"id": "a:25103169967870:RktIDUt:1",
"customer": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "USD Wallet"
},
"status": "ACTIVE",
"balance": {
"amount": 9714.04,
"currency": "USD"
},
"capabilities": {
"safeguarded": false,
"currencyType": "FIAT"
}
},
{
"id": "a:25103169967874:Pu3Nd8e:1",
"customer": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Another Wallet"
},
"status": "ACTIVE",
"balance": {
"amount": 2450.75,
"currency": "EUR"
},
"capabilities": {
"safeguarded": true,
"currencyType": "FIAT"
}
},
{
"id": "a:25103169967875:Zk6Qm1t:1",
"customer": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Crypto Wallet"
},
"status": "ACTIVE",
"balance": {
"amount": 518.12,
"currency": "USDT"
},
"capabilities": {
"safeguarded": true,
"currencyType": "CRYPTO"
}
}
],
"pageable": {
"pageNumber": 0,
"pageSize": 10
},
"hasNext": false
}
Receive the webhook
To get notified when the a new wallet is created, listen to the Ledger wallet creation notification.
What's next?
Now you have created a wallet, you can start sending and receiving payments.
- See the available use cases to select the one that best suits your needs.
- Configure a designated wallet for customer fees.