Getting started

Integrate with our API in minutes.

This guide walks technical users (integrators) through the process of spending via the Bando Spending Protocol (BSP). The flow involves retrieving products, creating a quote, paying with a wallet, registering the transaction, and tracking its status.

📘 OpenAPI Specification

---

Full Flow Summary

Step	Action	Method	Endpoint
1	Get products	GET	/products/grouped/
2	Get supported assets	GET	/tokens/{networkKey}/
3	Create quote	POST	/quotes/
4	Wallet payment (external)	Performed in the client	N/A
5	Register transaction	POST	/wallets/{address}/transactions/
6	Track transaction status	GET	/wallets/{address}/transactions/{transactionId}/

1. 🔎 Discover Available Products

Endpoint: GET /products/grouped/

This endpoint returns all spendable products grouped by category.

Retrieve the list of available products, filtered by country and other attributes.

get

Query parameters

pageNumberintegerOptional

Page number (starts from 1)

Default: 1

pageSizeintegerOptional

Page size (number of items per page)

Default: 100

brandstringOptional

Brand to filter

countrystringOptional

2 letter ISO code for the destination country to filter

typestringOptional

Product type to filter

subTypestringOptional

Offer subtype to filter

categorystringOptional

Product category name to filter. Supports multiple categories with comma-separated values: category=Mobile Data,Gaming Cards

Responses

200

OK

application/json

400

Bad Request

application/json

401

Unauthorized - API Token Missing or Unrecognized

application/json

403

Forbidden - IP Not Allowed

application/json

500

Internal Server Error

application/json

get

HTTPcURLJavaScriptPython

GET /api/v1/products/grouped/ HTTP/1.1
Host: api.bando.cool
Accept: */*

{
  "products": [
    {
      "productType": "text",
      "brands": [
        {
          "brandName": "text",
          "brandSlug": "text",
          "imageUrl": "text",
          "order": 1,
          "variants": [
            {
              "id": "text",
              "fupId": "text",
              "brand": "text",
              "country": "text",
              "notes": "text",
              "sku": "text",
              "price": {
                "fiatCurrency": "text",
                "fiatValue": "text",
                "stableCoinCurrency": "text",
                "stableCoinValue": "text"
              },
              "productType": "text",
              "referenceType": {
                "name": "text",
                "valueType": "text",
                "regex": "text"
              },
              "requiredFields": [
                {
                  "name": "text",
                  "valueType": "text",
                  "regex": "text"
                }
              ],
              "shortNotes": "text",
              "subTypes": [
                "text"
              ],
              "supportedCountries": [
                "text"
              ],
              "imageUrl": "text",
              "evmServiceId": 1,
              "svmServiceId": 1,
              "dataGB": "text",
              "dataSpeeds": [
                "text"
              ],
              "dataUnlimited": true,
              "durationDays": "text",
              "smsNumber": "text",
              "smsUnlimited": true,
              "voiceMinutes": "text",
              "voiceUnlimited": true,
              "roamingCountryIso2": "text",
              "roamingDataSpeeds": [
                "text"
              ]
            }
          ]
        }
      ]
    }
  ]
}

---

2. Fetch available chains and supported assets

Endpoints:

• GET /networks/

• GET /tokens/{networkKey}

Get supported blockchain networks

get

Responses

200

List of supported networks

application/json

400

API error responses

get

HTTPcURLJavaScriptPython

GET /api/v1/networks/ HTTP/1.1
Host: api.bando.cool
Accept: */*

{
  "success": true,
  "data": [
    {
      "name": "Arbitrum",
      "key": "arb",
      "logoUrl": "https://example.com",
      "chainId": 42161,
      "rpcUrl": "https://example.com",
      "explorerUrl": "https://example.com",
      "isTestnet": true,
      "networkType": "EVM",
      "isActive": true,
      "rank": 1,
      "protocolContracts": {},
      "nativeToken": {
        "name": "text",
        "symbol": "text",
        "coinKey": "text",
        "address": "text",
        "decimals": 1,
        "logoURI": "https://example.com"
      }
    }
  ]
}

Retrieve the list of supported tokens available for the specified blockchain network.

get

Path parameters

networkKeystringRequired

Network key identifier (e.g., arb, sol)

Responses

200

List of supported tokens

application/json

400

API error responses

get

HTTPcURLJavaScriptPython

GET /api/v1/tokens/{networkKey}/ HTTP/1.1
Host: api.bando.cool
Accept: */*

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "text",
      "symbol": "text",
      "key": "text",
      "address": "text",
      "decimals": 1,
      "friendlyDecimals": 1,
      "imageUrl": "https://example.com",
      "minAllowance": "text",
      "maxAllowance": "text"
    }
  ]
}

---

3. 💬 Create a Quote

Endpoint: POST /quotes/

Get a conversion quote for fiat to digital assets

post

Body

fiatCurrencystringRequired

Fiat currency for request.

digitalAssetstringRequired

Requested stable coin used for pricing (e.g., USDC)

skustringRequired

Product identifier

chainIdintegerRequired

Network identifier

integratorstringOptional

Integrator name

senderstringOptional

Sender address for the transaction

Responses

201

Quote retrieved successfully

application/json

400

Bad Request - Invalid or missing parameters

application/json

post

HTTPcURLJavaScriptPython

POST /api/v1/quotes/ HTTP/1.1
Host: api.bando.cool
Content-Type: application/json
Accept: */*
Content-Length: 106

{
  "fiatCurrency": "text",
  "digitalAsset": "text",
  "sku": "text",
  "chainId": 1,
  "integrator": "text",
  "sender": "text"
}

{
  "id": 1,
  "fiatCurrency": "text",
  "fiatAmount": "text",
  "digitalAsset": "text",
  "digitalAssetAmount": "text",
  "totalAmount": "text",
  "feeAmount": "text",
  "sku": "text",
  "transactionRequest": {
    "chainId": 1,
    "type": 2,
    "to": "text",
    "data": "text",
    "value": "text",
    "gas": "text",
    "gasLimit": "text",
    "maxFeePerGas": "text",
    "maxPriorityFeePerGas": "text"
  }
}

---

4. 💸 Perform Wallet Payment

When you're outside the BSP, you can use the quote response transactionRequest property to send crypto using a wallet (such as MetaMask, WalletConnect, CLI, etc.).

Here's what you do:

• Wait for the transaction to get a receipt. We recommend to wait for at last one confirmation on the blockchain.

• Start the transfer and make sure to grab the payment transaction hash.

• Th transaction returned by the API is compatible with most JS clients. But make sure to format it according to your implementation.

---

5. 📝 Register Spending Transaction

Endpoint: POST /wallets/{address}/transactions/

Use the sender’s wallet address in the path. Submit both quoteId and the paymentTxHash from the previous step.

Create a new spend transaction

post

Creates a new spending transaction in the Bando Spending Protocol.

Path parameters

addressstringRequired

User's wallet address

Query parameters

integratorstringRequired

Integrator slug unique identifier

Default: bando

Header parameters

Idempotency-Keystring · max: 255Required

Quote Unique key that makes this request idempotent.

Body

all ofOptional

and

Responses

201

Created spend transaction

application/json

400

Bad Request

application/json

401

Unauthorized - API Token Missing or Unrecognized

application/json

403

Forbidden - IP Not Allowed

application/json

404

Transactions not found

application/json

409

Duplicate request detected for this Idempotency-Key.

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

503

Indicates the client should retry the spending transaction due to an on-chain failure caused by network congestion.

application/json

post

HTTPcURLJavaScriptPython

POST /api/v1/wallets/{address}/transactions/ HTTP/1.1
Host: api.bando.cool
Idempotency-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 466

{
  "reference": "[email protected]",
  "requiredFields": [
    {
      "key": "Name",
      "value": "Linus"
    }
  ],
  "transactionIntent": {
    "sku": "SOME_SKU",
    "quantity": 1,
    "amount": 125.5,
    "chain": "42161",
    "token": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
    "wallet": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
    "integrator": "bando",
    "has_accepted_terms": true,
    "quote_id": 1
  },
  "transactionReceipt": {
    "hash": "0x6fd1f2b0c8cc2d63df046de3f3479a819efc954ed1ed363c1dbb43111488ea05",
    "virtualMachineType": "EVM"
  }
}

{
  "integrator": "text",
  "transactionId": "text",
  "status": "PENDING",
  "countryIsoAlpha2": "text",
  "productType": "not_set",
  "productSubType": "not_set",
  "sku": "not_set",
  "fiatUnitPrice": 0,
  "fiatCurrency": "text",
  "quantity": 1,
  "product": {
    "name": "Amazon PrePaid code",
    "logoUrl": "..."
  },
  "userWalletAddress": "text",
  "chainId": 1,
  "tokenUsed": "text",
  "tokenAmountPaid": 1,
  "created": "2025-08-07T01:04:29.813Z",
  "updated": "2025-08-07T01:04:29.813Z",
  "isDeleted": false,
  "givenReference": "text",
  "recordId": 1
}

---

6. 🔍 Track Transaction Status

Endpoint: GET /wallets/{address}/transactions/{transactionId}/

Use this to check the current status (PENDING, SUCCESS, or FAILED) of the transaction you registered.

Get spend transaction status and details

get

Path parameters

addressstringRequired

User's wallet address

transactionIdstring · uuidRequired

Transaction ID to retrieve

Query parameters

integratorstringRequired

Integrator slug unique identifier

Default: bando

Responses

200

Transaction retrieved successfully

application/json

400

Bad request

application/json

404

Transaction not found

application/json

412

Wrong transaction query parameters

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

get

HTTPcURLJavaScriptPython

GET /api/v1/wallets/{address}/transactions/{transactionId}/ HTTP/1.1
Host: api.bando.cool
Accept: */*

{
  "integrator": "text",
  "transactionId": "text",
  "status": "PENDING",
  "countryIsoAlpha2": "text",
  "productType": "not_set",
  "productSubType": "not_set",
  "sku": "not_set",
  "fiatUnitPrice": 0,
  "fiatCurrency": "text",
  "quantity": 1,
  "product": {
    "name": "Amazon PrePaid code",
    "logoUrl": "..."
  },
  "userWalletAddress": "text",
  "chainId": 1,
  "tokenUsed": "text",
  "tokenAmountPaid": 1,
  "created": "2025-08-07T01:04:29.813Z",
  "updated": "2025-08-07T01:04:29.813Z",
  "isDeleted": false,
  "givenReference": "text",
  "recordId": 1
}

---