Bando Docs
Launch AppLearn More
  • Bando for Developers
    • The On-chain Spending Protocol
    • Quickstart
    • Glossary
    • Use Cases
    • Protocol Architecture
      • Payment Reference Validation
      • Order Request
      • Order Fulfillment
      • Refunds
  • Spending Widget
    • Widget Quick Start
    • Installation
    • Configuration
    • Customization
    • Localization
    • Wallet Management
    • Framework Integration
      • Next.js
      • Svelte
  • Fulfiller API
    • Get Started with the API
    • Authentication
    • Guides
      • Get Available Products
      • Get a Payment Reference
      • Validate a payment reference
      • Get a Quote
      • Get Available Tokens for a Chain
    • API Reference
  • EVM Smart Contracts
    • EVM Smart Contracts | Architecture
    • Contracts
      • Core
        • BandoERC20Fulfillable
        • BandoFulfillmentManager
        • BandoFulfillable
        • BandoRouter
        • FulfillmentTypes
      • Libraries
        • FulfillmentRequestLib
        • SwapLib
      • Periphery
        • ERC20TokenRegistry
        • FulfillableRegistry
      • Proxy
        • Upgradeability
    • Security
      • Access Control
      • Security Considerations
      • Rekt Test
      • Audits
    • Code
Powered by GitBook
On this page

Was this helpful?

Edit on GitHub
  1. Fulfiller API

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 ChainNextEVM Smart Contracts | Architecture

Last updated 2 days 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
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
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"
              ],
              "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"
              ]
            }
          ]
        }
      ]
    }
  ]
}

Retrieve validated references

get
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-05-09T04:18:00.662Z",
    "updatedAt": "2025-05-09T04:18:00.662Z",
    "transactionIntent": {
      "sku": "text",
      "quantity": 1,
      "amount": 1,
      "chain": "text",
      "token": "text",
      "wallet": "text",
      "integrator": "text",
      "has_accepted_terms": true,
      "quote_id": 1,
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "validatedReferenceId": "123e4567-e89b-12d3-a456-426614174000",
      "status": "PENDING",
      "createdAt": "2025-05-09T04:18:00.662Z",
      "updatedAt": "2025-05-09T04:18:00.662Z"
    }
  }
]

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

Get transaction status and details

get
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: */*
{
  "transactionId": "text",
  "status": "PENDING",
  "countryIsoAlpha2": "text",
  "productType": "text",
  "productSubType": "text",
  "sku": "text",
  "fiatUnitPrice": 1,
  "fiatCurrency": "text",
  "quantity": 1,
  "product": {
    "name": "Amazon GiftCard",
    "logoUrl": "..."
  },
  "userWalletAddress": "text",
  "chainId": 1,
  "tokenUsed": "text",
  "tokenAmountPaid": 1,
  "created": "2025-05-09T04:18:00.662Z",
  "updated": "2025-05-09T04:18:00.662Z",
  "isDeleted": true,
  "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
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-05-09T04:18:00.662Z",
      "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,
      "imageUrl": "https://example.com",
      "minAllowance": "text",
      "maxAllowance": "text"
    }
  ]
}
  • GETGet list of existing products grouped by product type
  • GETRetrieve validated references
  • POSTCreate a new validated reference
  • POSTGet a conversion quote for fiat to digital assets
  • GETGet list of countries
  • GETGet country information by IP address
  • GETGet transaction status and details
  • GETGet supported blockchain networks
  • GETGet transactions by wallet address
  • GETGet wallet address state
  • GETGet supported tokens for a network

Create a new validated reference

post
Body
referencestringRequired

User-provided reference

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: 233

{
  "reference": "text",
  "requiredFields": [
    {
      "key": "text",
      "value": "text"
    }
  ],
  "transactionIntent": {
    "sku": "text",
    "quantity": 1,
    "amount": 1,
    "chain": "text",
    "token": "text",
    "wallet": "text",
    "integrator": "text",
    "has_accepted_terms": true,
    "quote_id": 1
  }
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "validationId": "text",
  "referenceType": "text",
  "status": "PENDING",
  "reference": "text",
  "requiredFields": {},
  "createdAt": "2025-05-09T04:18:00.662Z",
  "updatedAt": "2025-05-09T04:18:00.662Z",
  "transactionIntent": {
    "sku": "text",
    "quantity": 1,
    "amount": 1,
    "chain": "text",
    "token": "text",
    "wallet": "text",
    "integrator": "text",
    "has_accepted_terms": true,
    "quote_id": 1,
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "validatedReferenceId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "PENDING",
    "createdAt": "2025-05-09T04:18:00.662Z",
    "updatedAt": "2025-05-09T04:18:00.662Z"
  }
}

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

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: 90

{
  "fiatCurrency": "text",
  "digitalAsset": "text",
  "sku": "text",
  "chainId": 1,
  "integrator": "text"
}
{
  "id": 1,
  "fiatCurrency": "text",
  "fiatAmount": "text",
  "digitalAsset": "text",
  "digitalAssetAmount": "text",
  "totalAmount": "text",
  "feeAmount": "text",
  "sku": "text"
}