Skip to main content

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.

warning

Withdrawals are not an API call. They are a request to NAS that two NAS people approve. See Withdrawals.

What you can do​

You canCall
Create a walletCreate a wallet
List and read wallets and their balancesList all wallets, Get a wallet
Get a deposit addressCreate a blockchain address
See depositsList all blockchain transfers (read only)
Convert inside your walletsGet an estimate quote, Create a trade
Move money onto a card, or backCard transfer in, Card transfer out
Move money into a budget, or backIncrease 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"}'
Response POST /open-api/v3/cryptoconnect/wallets
{
"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"}'
Response POST /open-api/v3/cryptoconnect/wallets/{walletId}/addresses
{
"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​

CurrencyChain codes
USDCETH, BASE, AVAX, ARB, MATIC, OP, SOL, BNB
USDTETH, 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"
Response GET /open-api/v3/cryptoconnect/convert/currency-pair
{
"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"}'
Response POST /open-api/v3/cryptoconnect/convert/estimate-quote
{
"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:

  1. Addresses are whitelisted at onboarding. Two NAS people whitelist the addresses you may withdraw to. To add or change an address, ask NAS.
  2. 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.
  3. Two NAS people approve it. NAS then makes the transfer.
  4. 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 ETH and 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​

CodeHTTP statusWhat happened
NB40001400The call needs an accountId and none was sent.
NB40301403The account is not yours.
NB40302403The wallet, card or budget is not yours.
NB40303403The endpoint is not open to your client. Calls that send funds out are never open.
other400A validation message from card processing, for example an insufficient balance or an unsupported chain.

See Errors.