Wallets
A wallet holds one currency for one customer. A customer with USDT and NGN has two wallets.
You can read two sets of wallets with the same endpoints:
- Your own wallets, held by your partner account.
- Your customers' wallets, held by the business and individual customers you onboarded.
The wallet's owner tells you which is which. Your own wallets have owner.type Partner.
Endpoints
| Endpoint | Scope | |
|---|---|---|
| GET | /partner/v1/wallets | partner.read |
| GET | /partner/v1/wallets/{walletId} | partner.read |
Kinds and funding methods
Every wallet has a kind and a fundingMethod. They always come as a pair.
kind | fundingMethod | How money comes in | Deposit details |
|---|---|---|---|
Crypto | OnChain | A transfer on a blockchain network. | cryptoAddresses |
Fiat | Bank | A bank transfer. | bankAccounts |
The other list is always empty: a Crypto wallet has no bankAccounts, and a Fiat wallet has no cryptoAddresses.
Show deposit instructions
Show deposit details only for a wallet whose status is Active.
Crypto wallets
Each entry in cryptoAddresses is one address on one network. The same address can appear more than once, once for each network it accepts. For example, one EVM address can be listed for both Ethereum (eip155:1) and Base (eip155:8453).
Always show the network next to the address. A transfer sent on a network that is not listed for the wallet is not credited.
chainId is the network's CAIP-2 id. Use it to match the network in your own systems; use network as the label you show people.
Fiat wallets
Each entry in bankAccounts is one account the payer can send a bank transfer to. Show the fields that are not null:
bankNameandaccountNameaccountNumberbankCode,sortCodeoriban, depending on the country
A Fiat wallet can have no bank account. It cannot take deposits until it has one.
Balances
Get wallet returns a balance in the wallet's currency.
| Field | Meaning |
|---|---|
available | Money the owner can use now. |
pending | Money on its way in that is not usable yet. |
reserved | Money set aside for an operation in progress, such as a payout. |
balanceVersion | A number that increases on every balance change. |
There is no total field. If you need one, add available, pending and reserved.
Keep the highest balanceVersion you have seen for each wallet. A read with a lower balanceVersion is stale; ignore it.
Ownership
You see your own wallets and the wallets of customers under your partner account. Nothing else.
A wallet id that belongs to another partner returns 404 partner.wallet_not_found, exactly as an id that does not exist. The same applies to a customerId that is not yours: 404 partner.sub_customer_not_found. You cannot tell the two cases apart, by design.
Typical flow
List the wallets
Call List wallets. Pass customerId to see one customer's wallets.
Show deposit details
For each Active wallet, show the cryptoAddresses with their network, or the bankAccounts.
Read the balance
Call Get wallet with the walletId. There is no wallet or deposit webhook event today, so read the balance when you need it.
Shared response and error formats are on the API introduction.