API Reference

Complete API reference for Bando's Fulfiller endpoints. Detailed documentation for the integrating the first fully integrated web3 spending use-case for your wallet or Dapp.

PreviousGet Available Tokens for a Chain NextEVM Smart Contracts | Architecture

Last updated 1 month ago

Was this helpful?

Get list of existing products grouped by product type

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

Responses

200

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

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"
              ]
            }
          ]
        }
      ]
    }
  ]
}

Deprecated

Retrieve validated references

get

☠️ This endpoint will be decommissioned on Aug 1, 2025. No useful at all, No replacement.

Query parameters

validationIdstringOptional

Validation ID to filter references

Responses

200

Get validated reference

application/json

400

Bad Request

get

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

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "validationId": "text",
    "referenceType": "text",
    "status": "PENDING",
    "reference": "text",
    "requiredFields": {},
    "createdAt": "2025-06-13T13:58:57.749Z",
    "updatedAt": "2025-06-13T13:58:57.749Z",
    "transactionIntent": {
      "sku": "SOME_SKU",
      "quantity": 1,
      "amount": 125.5,
      "chain": "42161",
      "token": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
      "wallet": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
      "integrator": "bando",
      "has_accepted_terms": true,
      "quote_id": 1,
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "validatedReferenceId": "123e4567-e89b-12d3-a456-426614174000",
      "status": "PENDING",
      "createdAt": "2025-06-13T13:58:57.749Z",
      "updatedAt": "2025-06-13T13:58:57.749Z"
    }
  }
]

Get list of countries

get

Query parameters

regionstringOptional

Filter countries by region

subregionstringOptional

Filter countries by subregion

fiatCurrencystringOptional

Filter countries by fiat currency

searchstringOptional

Search in country name and capital

Responses

200

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

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

{
  "message": "Countries retrieved successfully",
  "data": {
    "count": 250,
    "results": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "United States",
        "isoAlpha2": "US",
        "isoAlpha3": "USA",
        "isCurrent": "true",
        "capital": "Washington, D.C.",
        "fiatCurrency": "USD",
        "region": "North America",
        "subregion": "Northern America",
        "languages": {
          "eng": "English"
        },
        "flagUrl": "https://example.com/flags/us.png",
        "timezone": "UTC-05:00",
        "latitude": 38.8951,
        "longitude": -77.0364,
        "callingCode": "+1",
        "status": "active",
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

Get country information by IP address

get

Query parameters

ipstringOptional

IP addreess to get geodata.

Responses

200

application/json

400

Bad Request

application/json

401

Unauthorized - API Token Missing or Unrecognized

application/json

403

Forbidden - IP Not Allowed

application/json

404

Not found

application/json

500

Internal Server Error

application/json

get

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

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "United States",
  "isoAlpha2": "US",
  "isoAlpha3": "USA",
  "isCurrent": "true",
  "capital": "Washington, D.C.",
  "fiatCurrency": "USD",
  "region": "North America",
  "subregion": "Northern America",
  "languages": {
    "eng": "English"
  },
  "flagUrl": "https://example.com/flags/us.png",
  "timezone": "UTC-05:00",
  "latitude": 38.8951,
  "longitude": -77.0364,
  "callingCode": "+1",
  "status": "active",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

Deprecated

Get transaction status and details

get

⚠️ This endpoint will be decommissioned on Aug 1, 2025. Please use GET /wallets/{address}/transactions/{transactionId} instead.

Path parameters

transactionIdstring · uuidRequired

Transaction ID to retrieve

Responses

200

Transaction retrieved successfully

application/json

404

Transaction not found

application/json

429

Too Many Requests

application/json

get

GET /api/v1/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-06-13T13:58:57.749Z",
  "updated": "2025-06-13T13:58:57.749Z",
  "isDeleted": false,
  "givenReference": "text",
  "recordId": 1
}

Get supported blockchain networks

get

Responses

200

List of supported networks

application/json

400

API error responses

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"
      }
    }
  ]
}

Get transactions by wallet address

get

Path parameters

addressstringRequired

User's wallet address

Query parameters

integratorstringRequired

Integrator slug unique identifier

Default: bando

chainIdintegerOptional

Blockchain network identifier

Default: null

pageNumberintegerOptional

Page number (starts from 1)

Default: 1

pageSizeintegerOptional

Page size (number of items per page)

Default: 100

Responses

200

List of transactions

application/json

400

Wrong parameters

application/json

404

Transactions not found

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

get

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

{
  "totalItems": 1,
  "totalPages": 1,
  "currentPage": 1,
  "transactions": [
    {
      "id": "b3d7ac95-ca57-45a0-8b15-5c6e1d1f2966",
      "status": "COMPLETED",
      "price": {
        "fiatCurrency": "text",
        "fiatValue": "text",
        "stableCoinCurrency": "text",
        "stableCoinValue": "text"
      },
      "productType": "topup",
      "productSku": "fc4f8917-b239-43e5-935b-88af43ee9da7",
      "quantity": "1",
      "chainId": 1,
      "tokenUsed": "text",
      "tokenAmountPaid": 1,
      "imageUrl": "text",
      "created": "2025-06-13T13:58:57.749Z",
      "brandName": "text",
      "walletAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
      "blockchainTransactionHash": "0x6fd1f2b0c8cc2d63df046de3f3479a819efc954ed1ed363c1dbb43111488ea05",
      "serviceId": 1,
      "recordId": 1
    }
  ]
}

Get wallet address state

get

Path parameters

addressstringRequired

User's wallet address

Query parameters

integratorstringRequired

Integrator slug unique identifier

Default: bando

Responses

200

Wallet state

application/json

400

Wrong parameters

application/json

404

Wallet not found

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

get

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

{
  "wallet": {
    "walletAddress": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
    "hasAcceptedTerms": true
  }
}

Get supported tokens for a 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

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"
    }
  ]
}

Deprecated

Create a new validated reference

post

⚠️ This endpoint will be decommissioned on Aug 1, 2025. Please use POST /wallets/{address}/transactions/ instead.

Body

referencestringRequired

User-provided reference

Example: some_email@someserver.io

transactionIntentall ofOptional

Required fields for validating the reference in JSON format

Responses

201

Reference created successfully

application/json

400

Invalid input

post

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

{
  "reference": "some_email@someserver.io",
  "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
  }
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "validationId": "text",
  "referenceType": "text",
  "status": "PENDING",
  "reference": "text",
  "requiredFields": {},
  "createdAt": "2025-06-13T13:58:57.749Z",
  "updatedAt": "2025-06-13T13:58:57.749Z",
  "transactionIntent": {
    "sku": "SOME_SKU",
    "quantity": 1,
    "amount": 125.5,
    "chain": "42161",
    "token": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
    "wallet": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
    "integrator": "bando",
    "has_accepted_terms": true,
    "quote_id": 1,
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "validatedReferenceId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "PENDING",
    "createdAt": "2025-06-13T13:58:57.749Z",
    "updatedAt": "2025-06-13T13:58:57.749Z"
  }
}

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

Invalid input

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"
  }
}