Wallets and funding
Money comes into your programme through deposits. From there you can convert between currencies and move money onto cards and budgets. This API moves money in. It has no call that sends funds to an external address.
Withdrawals are not an API call. They are a request to NAS that two NAS people approve. See Withdrawals.
What you can do
| You can | Call |
|---|---|
| Create a wallet | Create a wallet |
| List and read wallets and their balances | List all wallets, Get a wallet |
| Get a deposit address | Create a blockchain address |
| See deposits | List all blockchain transfers (read only) |
| Convert inside your wallets | Get an estimate quote, Create a trade |
| Move money onto a card, or back | Card transfer in, Card transfer out |
| Move money into a budget, or back | Increase budget balance, Decrease budget balance |
You cannot send crypto to an address, refund to an external address, or move money between accounts. Those calls do not exist, and a request for one is refused with NB40303.
Step 1 — Create a wallet
Every account has a master wallet. Create more wallets to keep funds apart, for example one per product. Send a referenceId that is a UUID v4 and unique to the wallet.
curl -X POST "https://sandbox-api.nas.cards/open-api/v3/cryptoconnect/wallets" \
-H "x-access-token: $ACCESS_TOKEN" \
-H "Idempotency-Key: 907d6edf-0033-4629-bcba-ee0363b5e737" \
-H "Content-Type: application/json" \
-d '{"accountId": "<account-id>", "referenceId": "907d6edf-0033-4629-bcba-ee0363b5e737", "nickname": "Developer"}'
{
"code": "000000",
"message": "success",
"data": {
"id": "907d6edf-0033-4629-bcba-ee0363b5e737",
"accountId": "b27c8873-e400-47cd-adc1-035cfa0d5347",
"nickname": "Developer",
"master": false,
"referenceId": "907d6edf-0033-4629-bcba-ee0363b5e737",
"balances": [
{ "currency": "USDC", "available": "0", "frozen": "0", "pending": "0" },
{ "currency": "USDT", "available": "0", "frozen": "0", "pending": "0" }
]
}
}
Step 2 — Get a deposit address
Ask for an address for one currency on one chain.
curl -X POST "https://sandbox-api.nas.cards/open-api/v3/cryptoconnect/wallets/<wallet-id>/addresses" \
-H "x-access-token: $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"currency": "USDC", "chain": "ETH"}'
{
"code": "000000",
"message": "success",
"data": {
"currency": "USDC",
"chain": "ETH",
"address": "0x6840238f8b024579e3897103b374b148101e3176",
"selected": true,
"status": "ACTIVE"
}
}
An address belongs to one currency on one chain. Send only that currency on that chain to it. Funds sent on another chain, or in another currency, may be lost.
Supported chains and currencies
| Currency | Chain codes |
|---|---|
| USDC | ETH, BASE, AVAX, ARB, MATIC, OP, SOL, BNB |
| USDT | ETH, BNB, SOL |
A pair that is not supported is refused with a validation error. BTC and ETH cannot be deposited or converted.
Step 3 — Watch deposits arrive
A deposit shows in your wallet balance, in the transfer list, and as a BLOCKCHAIN_TRANSFER.CREATED and BLOCKCHAIN_TRANSFER.UPDATE event.
curl "https://sandbox-api.nas.cards/open-api/v3/cryptoconnect/transfers?accountId=$ACCOUNT_ID" \
-H "x-access-token: $ACCESS_TOKEN"
A transfer is PENDING until the chain confirms it, then COMPLETE. Other states are FAILED and ONHOLD. Only act on COMPLETE.
Step 4 — Convert
Convert between currencies you hold, for example USDC to USD. First read the pair to see the minimum, then ask for a quote, then place the trade.
curl "https://sandbox-api.nas.cards/open-api/v3/cryptoconnect/convert/currency-pair?fromCurrency=USDC&toCurrency=USD" \
-H "x-access-token: $ACCESS_TOKEN"
{
"code": "000000",
"message": "success",
"data": {
"symbol": "USDC-USD",
"baseCurrency": "USDC",
"baseMin": "0.5",
"quoteCurrency": "USD",
"quoteMin": "0.5"
}
}
A quote is for information. It shows the rate, the fee and how long the quote lasts (ttlMs).
curl -X POST "https://sandbox-api.nas.cards/open-api/v3/cryptoconnect/convert/estimate-quote" \
-H "x-access-token: $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"accountId": "<account-id>", "baseCurrency": "USDC", "quoteCurrency": "USD", "side": "SELL", "rfqCurrency": "USDC", "rfqAmount": "100"}'
{
"code": "000000",
"message": "success",
"data": {
"id": "60de9a70-e58a-429c-a4de-ca5899f535c3",
"baseCurrency": "USDC",
"baseAmount": "100",
"quoteCurrency": "USD",
"quoteAmount": "99.5",
"side": "SELL",
"rate": "1",
"rfqAmount": "100",
"rfqCurrency": "USDC",
"fee": "0.5",
"feeCurrency": "USDC",
"ttlMs": "60000",
"quoteTime": "1752743982396"
}
}
Place the trade with a UUID referenceId. Retrying with the same referenceId never converts twice. The trade is refused if the wallet balance is too low.
curl -X POST "https://sandbox-api.nas.cards/open-api/v3/cryptoconnect/convert/trades" \
-H "x-access-token: $ACCESS_TOKEN" \
-H "Idempotency-Key: 143541d1-2753-4cfb-9e1e-2b57ddf5c27a" \
-H "Content-Type: application/json" \
-d '{"accountId": "<account-id>", "referenceId": "143541d1-2753-4cfb-9e1e-2b57ddf5c27a", "baseCurrency": "USDC", "quoteCurrency": "USD", "side": "SELL", "rfqCurrency": "USDC", "rfqAmount": "100"}'
A trade is PENDING, COMPLETE or FAILED.
Step 5 — Fund a card
Move money from your card account balance onto a card with Card transfer in. Take it back with Card transfer out. Both need a clientTransactionId that is unique to the call.
curl -X POST "https://sandbox-api.nas.cards/open-api/v3/cards/transfer-in" \
-H "x-access-token: $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"accountId": "<account-id>", "cardId": "<card-id>", "clientTransactionId": "5b1e3f0c-8d2a-4e7b-9c1f-0a6d4b2e8f31", "amount": "10"}'
NAS confirms how your card account balance is funded during onboarding. This guide does not describe a route from a wallet to that balance. The smallest transfer in is 0.1. The smallest transfer out is 0.01. Both appear as card transactions. See Transactions.
Budget cards draw on a budget instead of holding their own balance. Fund a budget with Increase budget balance.
Withdrawals
You cannot withdraw by API. A stolen key can therefore never move funds out of your programme.
NAS handles a withdrawal as a request, in this way:
- Addresses are whitelisted at onboarding. Two NAS people whitelist the addresses you may withdraw to. To add or change an address, ask NAS.
- You send the request by email. Email the withdrawal request from your registered contact to the NAS operations address given to you at onboarding. It states the amount, the currency, the chain and the whitelisted address.
- Two NAS people approve it. NAS then makes the transfer.
- NAS completes it by the next business day.
A request that names an address that is not whitelisted, or that does not come from your registered contact, is not processed.
Sandbox deposits
The sandbox runs on test networks with test funds. These limits apply.
- No simulated deposit. There is no call that makes a test deposit. A deposit needs a real transfer of test funds on a test network.
- One deposit route. Deposits are credited only for USDC on the Ethereum test network (Sepolia). Generate the address with chain
ETHand send test USDC to it from a test-USDC faucet. - Other chains give addresses only. You can generate addresses for the other chains in the table, but the sandbox does not credit deposits to them. Treat deposits on those chains as production only.
- Balances start at zero. A new sandbox wallet holds no funds. A conversion or a card transfer fails with an insufficient balance until a test deposit arrives.
Errors
| Code | HTTP status | What happened |
|---|---|---|
NB40001 | 400 | The call needs an accountId and none was sent. |
NB40301 | 403 | The account is not yours. |
NB40302 | 403 | The wallet, card or budget is not yours. |
NB40303 | 403 | The endpoint is not open to your client. Calls that send funds out are never open. |
| other | 400 | A validation message from card processing, for example an insufficient balance or an unsupported chain. |
See Errors.