Launch AppLearn More

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
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
get
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
Query parameters
walletAddressstringOptional

User's wallet address

Responses
200

List of supported networks

application/json
get
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)

Query parameters
walletAddressstringOptional

User's wallet address

Responses
200

List of supported tokens

application/json
get
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
post
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
post
POST /api/v1/wallets/{address}/transactions/ HTTP/1.1
Host: api.bando.cool
Idempotency-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 463

{
  "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",
    "hasAcceptedTerms": true,
    "quoteId": 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-14T00:21:45.931Z",
  "updated": "2025-08-14T00:21:45.931Z",
  "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
get
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-14T00:21:45.931Z",
  "updated": "2025-08-14T00:21:45.931Z",
  "isDeleted": false,
  "givenReference": "text",
  "recordId": 1
}
PreviousSvelteNextAuthentication

Last updated

Was this helpful?