Skip to content
Developer platform

Build on Africa's stablecoin market.

Every AfriFlux API uses one key and one credit balance. Start with 200 free credits when you sign up.

QuickstartPricingOpenAPI specPostman collection

Quickstart

  1. 01
    Create an account

    You start with 200 free credits, usable on every API.

  2. 02
    Copy a test key

    Create an af_test_ key in the dashboard. Test calls are free and return sample data.

  3. 03
    Make your first call

    Run the request below, or use the playground in any API's section.

curl "https://api.afriflux.xyz/v1/labels/base/0x0000000000000000000000000000000000000001" \
  -H "Authorization: Bearer af_test_YOUR_KEY"

Or use an SDK

One file each for JavaScript (Node 18+) and Python (3.8+), with no dependencies. Every API is a method. Both retry rate limits and server errors, and send the same idempotency key on each retry, so a retried call is charged once. They are built from the live documentation, so download them again when a new API appears.

// curl -O https://api.afriflux.xyz/v1/sdk/afriflux.js
import { AfriFlux } from "./afriflux.js";

const afriflux = new AfriFlux({ apiKey: process.env.AFRIFLUX_API_KEY });
console.log(await afriflux.walletLabels.labelLookup("base", "0x0000000000000000000000000000000000000001"));
# curl -O https://api.afriflux.xyz/v1/sdk/afriflux.py
from afriflux import AfriFlux

afriflux = AfriFlux()  # reads AFRIFLUX_API_KEY
print(afriflux.wallet_labels.label_lookup("base", "0x0000000000000000000000000000000000000001"))
Wallet Labels APISee rates

Who is this wallet associated with?

Find out which African venue an address belongs to, and what the venue uses it for. You pay only when we know the answer.

What it covers

10 African companies across 12 chains: 88 labelled addresses. An address outside this coverage comes back unmatched, and an unmatched lookup is free. Call GET /v1/labels/coverage with any key for the full list of entities, their chains and the roles we can return. It costs nothing.

arbitrumbasebscceloethereumliskoptimismplasmapolygonsolanatontron
RoleMeaningTier
depositA deposit address the venue assigned to one customer.standard
hot_walletA wallet the venue collects funds into or pays customers from.operational
treasuryThe venue's own treasury.operational
settlementA wallet the venue uses to settle with partners, desks or exchanges.operational
gas_funderA wallet that funds network fees for the venue's other wallets.operational
fee_walletA wallet that collects the venue's fees.operational
  • You pay only for answers: unmatched addresses are free, and matches cost more for a venue's own operational wallets than for customer deposit addresses. Answers you have paid for stay free until their valid_until.
  • Operational wallets (hot wallets, treasuries, settlement, gas and fee wallets) are answered once your account has bought credits. On free credits only, they come back unmatched and cost nothing.
  • Each new address in a request needs 10 credits available before the lookup runs, and you are only charged for addresses we match. If your balance is short, the error says how many addresses you can send.

Labels are analytical signals, not proof of legal ownership, sanctions or criminal conduct.

GET/v1/labels/{chain}/{address}

Look up one wallet label

Returns who an address belongs to and what it is used for. Unmatched addresses are free; matches are charged by tier. Your balance must cover an operational match before the lookup runs.

Cost: Free if unmatched · 3 credits per matched deposit label · 10 credits per matched operational label

curl "https://api.afriflux.xyz/v1/labels/base/0x0000000000000000000000000000000000000001" \
  -H "Authorization: Bearer af_test_YOUR_KEY"
Example response
{
  "address": "0x0000000000000000000000000000000000000001",
  "chain": "base",
  "matched": true,
  "entity": "AfriFlux Sandbox Exchange",
  "category": "exchanges",
  "role": "hot_wallet",
  "tier": "operational",
  "confidence": "high",
  "first_seen": "2024-03-01",
  "last_seen": "2026-01-01",
  "evidence": "operational_trace",
  "valid_until": "2026-10-19T12:00:00.000Z",
  "attribution_id": "attr_01J...",
  "license_fingerprint": "afl_9dc8..."
}
POST/v1/labels/batch

Look up a batch of wallet labels

Deduplicates identical chain/address pairs, then charges only for matches. meta.billed shows how many standard and operational matches you paid for.

Cost: Free if unmatched · 3 credits per matched deposit label · 10 credits per matched operational label

curl -X POST "https://api.afriflux.xyz/v1/labels/batch" \
  -H "Authorization: Bearer af_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"wallets":[{"chain":"base","address":"0x0000000000000000000000000000000000000001"},{"chain":"bsc","address":"0x0000000000000000000000000000000000000003"},{"chain":"base","address":"0x00000000000000000000000000000000000000ff"}]}'
Example response
{
  "data": [
    {
      "address": "0x0000000000000000000000000000000000000001",
      "chain": "base",
      "matched": true,
      "entity": "AfriFlux Sandbox Exchange",
      "category": "exchanges",
      "role": "hot_wallet",
      "tier": "operational",
      "confidence": "high",
      "first_seen": "2024-03-01",
      "last_seen": "2026-01-01",
      "evidence": "operational_trace",
      "valid_until": "2026-10-19T12:00:00.000Z",
      "attribution_id": "attr_01J...",
      "license_fingerprint": "afl_9dc8..."
    },
    {
      "address": "0x0000000000000000000000000000000000000003",
      "chain": "bsc",
      "matched": true,
      "entity": "AfriFlux Sandbox Exchange",
      "category": "exchanges",
      "role": "deposit",
      "tier": "standard",
      "confidence": "high",
      "first_seen": "2025-02-20",
      "last_seen": "2026-01-01",
      "evidence": "deposit_activity",
      "valid_until": "2026-10-19T12:00:00.000Z",
      "attribution_id": "attr_01J...",
      "license_fingerprint": "afl_9dc8..."
    },
    {
      "address": "0x00000000000000000000000000000000000000ff",
      "chain": "base",
      "matched": false,
      "entity": null,
      "category": null,
      "role": null,
      "tier": null,
      "confidence": null,
      "first_seen": null,
      "last_seen": null,
      "evidence": null,
      "valid_until": "2026-10-13T12:00:00.000Z",
      "attribution_id": "attr_01J...",
      "license_fingerprint": "afl_41ab..."
    }
  ],
  "meta": {
    "unique_wallets": 3,
    "matched": 2,
    "billed": {
      "standard": 1,
      "operational": 1
    },
    "credits_used": 13
  }
}
GET/v1/labels/coverage

See what we cover

Lists every entity we label, its chains and the public roles we can return for it. Free. Use it to judge coverage before you spend credits.

curl "https://api.afriflux.xyz/v1/labels/coverage" \
  -H "Authorization: Bearer af_test_YOUR_KEY"
Example response
{
  "as_of": "2026-10-11T04:00:00.000Z",
  "totals": {
    "entities": 26,
    "chains": 11,
    "labels": 874464
  },
  "chains": [
    "arbitrum",
    "base",
    "bsc",
    "celo",
    "ethereum",
    "lisk",
    "optimism",
    "polygon",
    "solana",
    "ton",
    "tron"
  ],
  "entities": [
    {
      "entity": "Quidax",
      "category": "exchanges",
      "chains": [
        "bsc",
        "ethereum",
        "tron"
      ],
      "roles": [
        "deposit",
        "hot_wallet",
        "settlement"
      ],
      "labels": 120000,
      "last_updated": "2026-10-11T04:00:00.000Z"
    }
  ]
}
GET/v1/usage

View account usage

Returns recent billable usage and month-to-date credit consumption. Paginate with limit and cursor; pass format=csv to download.

curl "https://api.afriflux.xyz/v1/usage?limit=50" \
  -H "Authorization: Bearer af_test_YOUR_KEY"
Example response
{
  "credits_used": 320,
  "requests": 281,
  "period_start": "2026-10-01T00:00:00.000Z",
  "recent": [],
  "next_cursor": null,
  "has_more": false,
  "limit": 50
}
GET/v1/credits

View credit balance and expiry

Returns the unexpired balance and credit-lot expiry schedule.

curl "https://api.afriflux.xyz/v1/credits" \
  -H "Authorization: Bearer af_test_YOUR_KEY"
Example response
{
  "balance": 4680,
  "lots": [
    {
      "remaining": 4680,
      "expires_at": "2027-07-13T00:00:00.000Z"
    }
  ]
}
GET/v1/health

Check API availability

Confirms that the published API product and serving database are available.

curl "https://api.afriflux.xyz/v1/health" \
  -H "Authorization: Bearer af_test_YOUR_KEY"
Example response
{
  "status": "ok",
  "product": "wallet_labels",
  "version": 1
}

Playground

Run real requests against the sandbox from your browser. Paste an af_test_ key from your dashboard; it stays in this tab and is only sent to the API. Live keys are rejected here.

Sandbox requests are free
Market Data APISee rates

What is happening in the market?

Token and universe time series, snapshots, and DEX-implied reference-rate prints for African stablecoins, served from AfriFlux's daily snapshot pipeline.

GET/v1/market-data/timeseries/{symbol}/{metric}

Query a token or universe time series

Returns aligned period/value points from the daily snapshot pipeline. Use symbol=universe with a bare universe metric (transfer, dex, mints, burns, users) for cross-token series; otherwise metric uses the form dimension:measure where dimension is chain, dex_project, venue, mint_flow, or burn_flow. Ranges are capped per grain (daily 400, weekly 300, monthly 160, quarterly 80 most-recent points) and responses flag truncated separately from partial_last so incomplete final periods are never mistaken for complete ones.

Cost: 1 credit · per request

curl "https://api.afriflux.xyz/v1/market-data/timeseries/cngn/chain%3Atransfer_usd?grain=daily&entity=base" \
  -H "Authorization: Bearer af_test_YOUR_KEY"
Example response
{
  "data": {
    "resource": "token_series",
    "symbol": "cNGN",
    "dimension": "chain",
    "measure": "transfer_usd",
    "grain": "daily",
    "entities": [
      "base"
    ],
    "series": {
      "base": [
        {
          "period": "2026-08-21",
          "value": 1842035.55
        },
        {
          "period": "2026-08-22",
          "value": 2104882.1
        }
      ]
    },
    "first_period": "2026-08-21",
    "last_period": "2026-08-22",
    "point_count": 2,
    "truncated": false,
    "partial_last": true
  },
  "meta": {
    "product": "market_data",
    "version": 1,
    "schema_version": 1,
    "as_of": "2026-08-23T04:12:00.000Z",
    "as_of_data_day": "2026-08-22",
    "partial_last": true,
    "attribution_id": "attr_01J8ZK4F2A9DQ7M3X5VBNP6RTS",
    "license_fingerprint": "afl_9dc81b9e5f0a4c2d7e11",
    "dataset_fingerprint": "ds_4f2a91c07be3d618"
  }
}
GET/v1/market-data/tokens/{symbol}/snapshot

Latest snapshot for one token

Curated latest cut for a single token: supply, lifetime flows, holders, transfer and DEX totals, TVL, and corridor count, with as_of provenance. Accepts the manifest slug or symbol (cngn, cNGN_mento, cngn-mento).

Cost: 2 credits · per request

curl "https://api.afriflux.xyz/v1/market-data/tokens/cngn/snapshot" \
  -H "Authorization: Bearer af_test_YOUR_KEY"
Example response
{
  "data": {
    "slug": "cngn",
    "symbol": "cNGN",
    "name": "cNGN",
    "issuer": "AfriFlux tracked issuer",
    "country": "Nigeria",
    "currency": "NGN",
    "decimals": 18,
    "status": "live",
    "launch_date": null,
    "chains": [
      "base"
    ],
    "supply": {
      "total_circulating": 4512300.42,
      "mint_volume_usd_30d": 312004.15,
      "burn_volume_usd_30d": 288910.02
    },
    "supply_by_chain": [
      {
        "chain": "base",
        "circulating_supply": 4512300.42
      }
    ],
    "lifetime": {
      "transfer_usd": 184220400.5,
      "transfer_native": 184220400.5,
      "dex_usd": 41002118.75,
      "mint_usd": 12402800,
      "burn_usd": 10998200.25,
      "transfer_count": 92441,
      "dex_trade_count": 30112
    },
    "holders": {
      "total_holders": 18204,
      "total_balance_usd": 4501220.14
    },
    "transfers_window": {
      "total_volume_usd": 9812442.31,
      "total_transfer_count": 12902
    },
    "dex": {
      "total_lifetime_volume_usd": 41002118.75,
      "total_lifetime_trades": 30112
    },
    "tvl": {
      "tvl_usd": 812400.5,
      "pool_count": 6,
      "snapshot_day": "2026-08-22"
    },
    "corridor_count": 4
  },
  "meta": {
    "product": "market_data",
    "version": 1,
    "schema_version": 1,
    "as_of": "2026-08-23T04:12:00.000Z",
    "as_of_data_day": "2026-08-22",
    "partial_last": true,
    "attribution_id": "attr_01J8ZK4F2A9DQ7M3X5VBNP6RTS",
    "license_fingerprint": "afl_9dc81b9e5f0a4c2d7e11",
    "dataset_fingerprint": "ds_4f2a91c07be3d618"
  }
}
GET/v1/market-data/universe/snapshot

Latest universe snapshot

Headline KPIs, the token leaderboard, and per-chain totals for the whole tracked stablecoin universe in one call.

Cost: 2 credits · per request

curl "https://api.afriflux.xyz/v1/market-data/universe/snapshot" \
  -H "Authorization: Bearer af_test_YOUR_KEY"
Example response
{
  "data": {
    "headline_kpis": {
      "total_circulating_usd": 21402118.44,
      "total_tokens": 7,
      "total_chains": 6,
      "total_holders": 96120,
      "total_balance_usd": 21100402.9,
      "transfers_30d": 214882,
      "transfer_volume_usd_30d": 61204882.15,
      "dex_trades_30d": 84102,
      "dex_volume_usd_30d": 18402215.6,
      "total_tvl_usd": 3912004.18
    },
    "token_leaderboard": [],
    "chains": []
  },
  "meta": {
    "product": "market_data",
    "version": 1,
    "schema_version": 1,
    "as_of": "2026-08-23T04:12:00.000Z",
    "as_of_data_day": "2026-08-22",
    "partial_last": true,
    "attribution_id": "attr_01J8ZK4F2A9DQ7M3X5VBNP6RTS",
    "license_fingerprint": "afl_9dc81b9e5f0a4c2d7e11",
    "dataset_fingerprint": "ds_4f2a91c07be3d618"
  }
}
GET/v1/market-data/rates/{symbol}/usd

DEX-implied USD reference rate (preview)

Daily volume-weighted implied USD price per token across chains, floored by minimum per-chain daily volume to suppress thin-pool noise. Preview methodology: history depth follows the published DEX window and prints may restate once the canonical reference-rate pipeline ships.

Cost: 2 credits · per request

curl "https://api.afriflux.xyz/v1/market-data/rates/cngn/usd?min_day_volume_usd=25000" \
  -H "Authorization: Bearer af_test_YOUR_KEY"
Example response
{
  "data": {
    "symbol": "cNGN",
    "quote": "usd",
    "preview": true,
    "methodology": {
      "method": "volume_weighted_daily_mean_of_chain_implied_prices",
      "liquidity_floor_usd": 25000,
      "note": "Preview methodology built on DEX-implied prices. A canonical reference-rate pipeline with a published methodology is pending; expect restatements."
    },
    "window": {
      "first_day": "2026-08-21",
      "last_day": "2026-08-22"
    },
    "days": [
      {
        "day": "2026-08-21",
        "implied_price_usd": 0.000651,
        "volume_usd": 412882.4,
        "trade_count": 210,
        "chains": [
          "base"
        ]
      },
      {
        "day": "2026-08-22",
        "implied_price_usd": 0.000649,
        "volume_usd": 388104.9,
        "trade_count": 198,
        "chains": [
          "base"
        ]
      }
    ]
  },
  "meta": {
    "product": "market_data",
    "version": 1,
    "schema_version": 1,
    "as_of": "2026-08-23T04:12:00.000Z",
    "as_of_data_day": "2026-08-22",
    "partial_last": true,
    "attribution_id": "attr_01J8ZK4F2A9DQ7M3X5VBNP6RTS",
    "license_fingerprint": "afl_9dc81b9e5f0a4c2d7e11",
    "dataset_fingerprint": "ds_4f2a91c07be3d618"
  }
}
GET/v1/market-data/health

Check API availability

Confirms that the published API product is available and identifies the serving environment.

curl "https://api.afriflux.xyz/v1/market-data/health" \
  -H "Authorization: Bearer af_test_YOUR_KEY"
Example response
{
  "status": "ok",
  "product": "market_data",
  "version": 1,
  "environment": "live",
  "time": "2026-08-23T04:12:00.000Z"
}

Playground

Run real requests against the sandbox from your browser. Paste an af_test_ key from your dashboard; it stays in this tab and is only sent to the API. Live keys are rejected here.

Sandbox requests are free
Wallet Screening APISee rates

Who is behind this wallet, and is it tied to frozen stablecoins?

One call for a compliance check. It tells you which African venue an address belongs to and what the venue uses it for, and whether a stablecoin issuer has frozen it or it is one step from frozen money, at the venues AfriFlux tracks. You pay only for the parts we have an answer for. Needs a paid account.

GET/v1/screen/{chain}/{address}

Screen one address

Returns the wallet label and the freeze record for one address. Each part has its own matched flag, and you pay only for the parts that matched. A label you already paid for stays free until its valid_until.

Cost: Free if unmatched · 3 credits per matched label · 10 credits per matched operational label · 5 credits per matched freeze record

curl "https://api.afriflux.xyz/v1/screen/ethereum/0x00000000000000000000000000000000000f0001" \
  -H "Authorization: Bearer af_test_YOUR_KEY"
Example response
{
  "address": "0x00000000000000000000000000000000000f0001",
  "chain": "ethereum",
  "label": {
    "matched": false,
    "entity": null,
    "category": null,
    "role": null,
    "tier": null,
    "confidence": null,
    "first_seen": null,
    "last_seen": null,
    "evidence": null
  },
  "freeze": {
    "matched": true,
    "frozen": true,
    "freeze_lists": [
      {
        "token": "USDT",
        "chain": "tron",
        "frozen_at": "2025-11-04T14:20:11+00:00",
        "first_frozen_at": "2025-11-04T14:20:11+00:00",
        "refrozen": false,
        "destroyed": null
      }
    ],
    "tracked_venues": {
      "direct": 2,
      "through_other_wallets": 1,
      "after_contact_with_frozen": 0
    },
    "paid_after_freeze": true,
    "freeze_risk": "high",
    "as_of": "2026-01-01T02:00:00Z"
  },
  "valid_until": "2026-11-13T12:00:00.000Z",
  "attribution_id": "attr_01J...",
  "license_fingerprint": "afl_41ab..."
}
POST/v1/screen/batch

Screen a batch of addresses

Screens many addresses at once. Duplicates count once, and you pay only for the parts that matched. Your plan sets the largest batch.

Cost: Free if unmatched · 3 credits per matched label · 10 credits per matched operational label · 5 credits per matched freeze record

curl -X POST "https://api.afriflux.xyz/v1/screen/batch" \
  -H "Authorization: Bearer af_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"wallets":[{"chain":"bsc","address":"0x0000000000000000000000000000000000000003"},{"chain":"ethereum","address":"0x00000000000000000000000000000000000f0001"}]}'
Example response
{
  "data": [
    {
      "address": "0x0000000000000000000000000000000000000003",
      "chain": "bsc",
      "label": {
        "matched": true,
        "entity": "AfriFlux Sandbox Exchange",
        "category": "exchanges",
        "role": "deposit",
        "tier": "standard",
        "confidence": "high",
        "first_seen": "2025-02-20",
        "last_seen": "2026-01-01",
        "evidence": "deposit_activity"
      },
      "freeze": {
        "matched": false,
        "frozen": false,
        "freeze_lists": [],
        "tracked_venues": {
          "direct": 0,
          "through_other_wallets": 0,
          "after_contact_with_frozen": 0
        },
        "paid_after_freeze": false,
        "freeze_risk": null,
        "as_of": "2026-01-01T02:00:00Z"
      },
      "valid_until": "2026-11-19T12:00:00.000Z",
      "attribution_id": "attr_01J...",
      "license_fingerprint": "afl_9dc8..."
    },
    {
      "address": "0x00000000000000000000000000000000000f0001",
      "chain": "ethereum",
      "label": {
        "matched": false,
        "entity": null,
        "category": null,
        "role": null,
        "tier": null,
        "confidence": null,
        "first_seen": null,
        "last_seen": null,
        "evidence": null
      },
      "freeze": {
        "matched": true,
        "frozen": true,
        "freeze_lists": [
          {
            "token": "USDT",
            "chain": "tron",
            "frozen_at": "2025-11-04T14:20:11+00:00",
            "first_frozen_at": "2025-11-04T14:20:11+00:00",
            "refrozen": false,
            "destroyed": null
          }
        ],
        "tracked_venues": {
          "direct": 2,
          "through_other_wallets": 1,
          "after_contact_with_frozen": 0
        },
        "paid_after_freeze": true,
        "freeze_risk": "high",
        "as_of": "2026-01-01T02:00:00Z"
      },
      "valid_until": "2026-11-13T12:00:00.000Z",
      "attribution_id": "attr_01J...",
      "license_fingerprint": "afl_41ab..."
    }
  ],
  "meta": {
    "unique_wallets": 2,
    "label_matched": 1,
    "freeze_matched": 1,
    "credits_used": 8
  }
}
GET/v1/screen/health

Check API availability

Confirms the API is available and which environment answered.

curl "https://api.afriflux.xyz/v1/screen/health" \
  -H "Authorization: Bearer af_test_YOUR_KEY"
Example response
{
  "status": "ok",
  "product": "wallet_screening",
  "version": 1,
  "environment": "live",
  "time": "2026-11-12T09:00:00.000Z"
}

Playground

Run real requests against the sandbox from your browser. Paste an af_test_ key from your dashboard; it stays in this tab and is only sent to the API. Live keys are rejected here.

Sandbox requests are free
Reference Data APISee rates

What assets, venues, chains and markets does AfriFlux track?

The AfriFlux master tables: tokens, venues, corridors, chains, countries, and the section coverage matrix, all keyed by stable slugs and stamped with snapshot provenance. Unmetered by design; every other AfriFlux API joins onto these identifiers.

GET/v1/reference/status

Reference catalog status

Entity counts, coverage-matrix symbols, and the as_of provenance stamp for the current snapshot.

curl "https://api.afriflux.xyz/v1/reference/status" \
  -H "Authorization: Bearer af_test_YOUR_KEY"
Example response
{
  "data": {
    "counts": {
      "tokens": 7,
      "venues": 26,
      "chains": 6,
      "corridors": 11,
      "countries": 5
    },
    "coverage_tokens": [
      "cGHS",
      "cKES",
      "cNGN",
      "cNGN_mento",
      "cZAR",
      "eXOF",
      "ZARP"
    ]
  },
  "meta": {
    "product": "reference",
    "version": 1,
    "schema_version": 1,
    "as_of": "2026-08-23T04:12:00.000Z",
    "as_of_data_day": "2026-08-22",
    "attribution_id": "attr_01J8ZK4F2A9DQ7M3X5VBNP6RTS",
    "license_fingerprint": "afl_9dc81b9e5f0a4c2d7e11",
    "dataset_fingerprint": "ds_1c88e2f40b7a95d3"
  }
}
GET/v1/reference/tokens

List tracked tokens

The token master: slug (canonical join key), symbol, issuer, country, currency, status, launch date, and chains. Filterable by status, chain, or country.

curl "https://api.afriflux.xyz/v1/reference/tokens?chain=base" \
  -H "Authorization: Bearer af_test_YOUR_KEY"
Example response
{
  "data": {
    "tokens": [
      {
        "slug": "cngn",
        "symbol": "cNGN",
        "name": "cNGN",
        "issuer": "AfriFlux tracked issuer",
        "country": "Nigeria",
        "currency": "NGN",
        "status": "live",
        "launch_date": null,
        "chains": [
          "base"
        ]
      }
    ]
  },
  "meta": {
    "product": "reference",
    "version": 1,
    "schema_version": 1,
    "as_of": "2026-08-23T04:12:00.000Z",
    "as_of_data_day": "2026-08-22",
    "attribution_id": "attr_01J8ZK4F2A9DQ7M3X5VBNP6RTS",
    "license_fingerprint": "afl_9dc81b9e5f0a4c2d7e11",
    "dataset_fingerprint": "ds_1c88e2f40b7a95d3"
  }
}
GET/v1/reference/tokens/{symbol}

Resolve one token plus its coverage matrix

A single token master row joined with its per-section coverage states, so clients can learn which datasets exist for the token before querying other products. Accepts slug or symbol in any hyphen/underscore form.

curl "https://api.afriflux.xyz/v1/reference/tokens/cngn" \
  -H "Authorization: Bearer af_test_YOUR_KEY"
Example response
{
  "data": {
    "slug": "cngn",
    "symbol": "cNGN",
    "name": "cNGN",
    "issuer": "AfriFlux tracked issuer",
    "country": "Nigeria",
    "currency": "NGN",
    "status": "live",
    "launch_date": null,
    "chains": [
      "base"
    ],
    "coverage": {
      "corridors": "live",
      "dex_pools": "live",
      "peg_deviation": "in_progress"
    }
  },
  "meta": {
    "product": "reference",
    "version": 1,
    "schema_version": 1,
    "as_of": "2026-08-23T04:12:00.000Z",
    "as_of_data_day": "2026-08-22",
    "attribution_id": "attr_01J8ZK4F2A9DQ7M3X5VBNP6RTS",
    "license_fingerprint": "afl_9dc81b9e5f0a4c2d7e11",
    "dataset_fingerprint": "ds_1c88e2f40b7a95d3"
  }
}
GET/v1/reference/chains

List supported chains

Chain slugs and display names usable as entity filters across all products.

curl "https://api.afriflux.xyz/v1/reference/chains" \
  -H "Authorization: Bearer af_test_YOUR_KEY"
Example response
{
  "data": {
    "chains": [
      {
        "slug": "base",
        "name": "Base"
      }
    ]
  },
  "meta": {
    "product": "reference",
    "version": 1,
    "schema_version": 1,
    "as_of": "2026-08-23T04:12:00.000Z",
    "as_of_data_day": "2026-08-22",
    "attribution_id": "attr_01J8ZK4F2A9DQ7M3X5VBNP6RTS",
    "license_fingerprint": "afl_9dc81b9e5f0a4c2d7e11",
    "dataset_fingerprint": "ds_1c88e2f40b7a95d3"
  }
}
GET/v1/reference/venues

List tracked venues

The venue master: roles, chain and token presence, first/last active day, and lifetime USD flow. Filterable by chain or role.

curl "https://api.afriflux.xyz/v1/reference/venues?country=NG" \
  -H "Authorization: Bearer af_test_YOUR_KEY"
Example response
{
  "data": {
    "venues": [
      {
        "slug": "obiex",
        "name": "Obiex",
        "category": "exchanges",
        "type": "CEX",
        "countries": [
          "CM",
          "GH",
          "NG"
        ],
        "status": "live",
        "books": [
          "retail",
          "business"
        ],
        "chains": [
          "arbitrum",
          "base",
          "bsc",
          "ethereum",
          "polygon",
          "solana",
          "tron"
        ],
        "label_roles": [
          "deposit",
          "hot_wallet",
          "gas_funder"
        ]
      }
    ]
  },
  "meta": {
    "product": "reference",
    "version": 1,
    "schema_version": 1,
    "as_of": "2026-08-23T04:12:00.000Z",
    "as_of_data_day": "2026-08-22",
    "attribution_id": "attr_01J8ZK4F2A9DQ7M3X5VBNP6RTS",
    "license_fingerprint": "afl_9dc81b9e5f0a4c2d7e11",
    "dataset_fingerprint": "ds_1c88e2f40b7a95d3"
  }
}
GET/v1/reference/corridors

List tracked corridors

The corridor master: base/quote token pairs per chain and project with lifetime trade counts. The enumeration for corridor analytics.

curl "https://api.afriflux.xyz/v1/reference/corridors?base=cNGN" \
  -H "Authorization: Bearer af_test_YOUR_KEY"
Example response
{
  "data": {
    "corridors": [
      {
        "slug": "cngn-usdt-base",
        "base": "cNGN",
        "quote": "USDT",
        "chains": [
          "base"
        ],
        "projects": [
          "uniswap"
        ],
        "lifetime_trades": 30112
      }
    ]
  },
  "meta": {
    "product": "reference",
    "version": 1,
    "schema_version": 1,
    "as_of": "2026-08-23T04:12:00.000Z",
    "as_of_data_day": "2026-08-22",
    "attribution_id": "attr_01J8ZK4F2A9DQ7M3X5VBNP6RTS",
    "license_fingerprint": "afl_9dc81b9e5f0a4c2d7e11",
    "dataset_fingerprint": "ds_1c88e2f40b7a95d3"
  }
}
GET/v1/reference/countries

List covered countries

Country slugs, names, and the tokens mapped to each currency area.

curl "https://api.afriflux.xyz/v1/reference/countries" \
  -H "Authorization: Bearer af_test_YOUR_KEY"
Example response
{
  "data": {
    "countries": [
      {
        "slug": "nigeria",
        "name": "Nigeria",
        "tokens": [
          "cNGN",
          "cNGN_mento"
        ]
      }
    ]
  },
  "meta": {
    "product": "reference",
    "version": 1,
    "schema_version": 1,
    "as_of": "2026-08-23T04:12:00.000Z",
    "as_of_data_day": "2026-08-22",
    "attribution_id": "attr_01J8ZK4F2A9DQ7M3X5VBNP6RTS",
    "license_fingerprint": "afl_9dc81b9e5f0a4c2d7e11",
    "dataset_fingerprint": "ds_1c88e2f40b7a95d3"
  }
}
GET/v1/reference/coverage

Dataset coverage matrix

Per-token, per-section dataset availability (live, in_progress, no_coverage_yet, not_applicable). Query this before consuming any metric to avoid silent gaps.

curl "https://api.afriflux.xyz/v1/reference/coverage" \
  -H "Authorization: Bearer af_test_YOUR_KEY"
Example response
{
  "data": {
    "legend": [
      "live",
      "in_progress",
      "no_coverage_yet",
      "not_applicable"
    ],
    "coverage": {
      "cNGN": {
        "corridors": "live",
        "dex_pools": "live",
        "peg_deviation": "in_progress"
      }
    }
  },
  "meta": {
    "product": "reference",
    "version": 1,
    "schema_version": 1,
    "as_of": "2026-08-23T04:12:00.000Z",
    "as_of_data_day": "2026-08-22",
    "attribution_id": "attr_01J8ZK4F2A9DQ7M3X5VBNP6RTS",
    "license_fingerprint": "afl_9dc81b9e5f0a4c2d7e11",
    "dataset_fingerprint": "ds_1c88e2f40b7a95d3"
  }
}
GET/v1/reference/health

Check API availability

Confirms that the published API product is available and identifies the serving environment.

curl "https://api.afriflux.xyz/v1/reference/health" \
  -H "Authorization: Bearer af_test_YOUR_KEY"
Example response
{
  "status": "ok",
  "product": "reference",
  "version": 1,
  "environment": "live",
  "time": "2026-08-23T04:12:00.000Z"
}

Playground

Run real requests against the sandbox from your browser. Paste an af_test_ key from your dashboard; it stays in this tab and is only sent to the API. Live keys are rejected here.

Freeze Check APISee rates

Is this address tied to frozen stablecoins?

Find out whether an address has been frozen by a stablecoin issuer, or is one step from frozen money, at the African venues AfriFlux tracks. You pay only when we have a record. No record means we hold nothing on the address, not that it is clear everywhere.

GET/v1/freeze/addresses/{address}

Check one address

Says whether the address is on an issuer's freeze list, how many venues we track it dealt with, and whether a venue paid it after the freeze. Venues are counted, never named. Free when we hold no record. Needs a paid account.

Cost: 5 credits · per matched address

curl "https://api.afriflux.xyz/v1/freeze/addresses/0x00000000000000000000000000000000000f0001" \
  -H "Authorization: Bearer af_test_YOUR_KEY"
Example response
{
  "address": "0x00000000000000000000000000000000000f0001",
  "matched": true,
  "frozen": true,
  "freeze_lists": [
    {
      "token": "USDT",
      "chain": "tron",
      "frozen_at": "2025-11-04T14:20:11+00:00",
      "first_frozen_at": "2025-11-04T14:20:11+00:00",
      "refrozen": false,
      "destroyed": null
    }
  ],
  "tracked_venues": {
    "direct": 2,
    "through_other_wallets": 1,
    "after_contact_with_frozen": 0
  },
  "paid_after_freeze": true,
  "freeze_risk": "high",
  "as_of": "2026-01-01T02:00:00Z"
}
POST/v1/freeze/batch

Check a batch of addresses

Checks many addresses at once. Duplicates count once, and you pay only for addresses we hold a record on. Your plan sets the largest batch.

Cost: 5 credits · per matched address

curl -X POST "https://api.afriflux.xyz/v1/freeze/batch" \
  -H "Authorization: Bearer af_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"addresses":["0x00000000000000000000000000000000000f0001","0x00000000000000000000000000000000000f0002","0x00000000000000000000000000000000000000ff"]}'
Example response
{
  "data": [
    {
      "address": "0x00000000000000000000000000000000000f0001",
      "matched": true,
      "frozen": true,
      "freeze_lists": [
        {
          "token": "USDT",
          "chain": "tron",
          "frozen_at": "2025-11-04T14:20:11+00:00",
          "first_frozen_at": "2025-11-04T14:20:11+00:00",
          "refrozen": false,
          "destroyed": null
        }
      ],
      "tracked_venues": {
        "direct": 2,
        "through_other_wallets": 1,
        "after_contact_with_frozen": 0
      },
      "paid_after_freeze": true,
      "freeze_risk": "high",
      "as_of": "2026-01-01T02:00:00Z"
    },
    {
      "address": "0x00000000000000000000000000000000000f0002",
      "matched": true,
      "frozen": false,
      "freeze_lists": [],
      "tracked_venues": {
        "direct": 0,
        "through_other_wallets": 0,
        "after_contact_with_frozen": 1
      },
      "paid_after_freeze": false,
      "freeze_risk": "medium",
      "as_of": "2026-01-01T02:00:00Z"
    },
    {
      "address": "0x00000000000000000000000000000000000000ff",
      "matched": false,
      "frozen": false,
      "freeze_lists": [],
      "tracked_venues": {
        "direct": 0,
        "through_other_wallets": 0,
        "after_contact_with_frozen": 0
      },
      "paid_after_freeze": false,
      "freeze_risk": null,
      "as_of": "2026-01-01T02:00:00Z"
    }
  ],
  "meta": {
    "unique_addresses": 3,
    "matched": 2,
    "credits_used": 10
  }
}
GET/v1/freeze/coverage

See what we cover

How many venues we track, on which chains, and how many frozen addresses have dealt with them. Free.

curl "https://api.afriflux.xyz/v1/freeze/coverage" \
  -H "Authorization: Bearer af_test_YOUR_KEY"
Example response
{
  "as_of": "2026-11-11T02:00:00Z",
  "tracked_venues": 26,
  "chains": [
    "ethereum",
    "tron"
  ],
  "frozen_addresses": 412
}
GET/v1/freeze/health

Check API availability

Confirms the API is available and which environment answered.

curl "https://api.afriflux.xyz/v1/freeze/health" \
  -H "Authorization: Bearer af_test_YOUR_KEY"
Example response
{
  "status": "ok",
  "product": "freeze_check",
  "version": 1,
  "environment": "live",
  "time": "2026-11-11T09:00:00.000Z"
}

Playground

Run real requests against the sandbox from your browser. Paste an af_test_ key from your dashboard; it stays in this tab and is only sent to the API. Live keys are rejected here.

Sandbox requests are free

Use with AI tools

AfriFlux runs an MCP server, the standard way to give AI apps tools. Add it to Claude, ChatGPT, Cursor or your own agent, and the app calls the tools below when you ask. Calls use your account's credits, cost the same as API calls, and appear in your request log.

https://www.afriflux.xyz/mcp

Claude or ChatGPT

  1. Add a custom connector with the address above.
  2. Sign in with AfriFlux, then choose your API account and test or live data.
  3. Ask, for example: “Screen 0x0000000000000000000000000000000000000003 on BSC.”

Connected apps are listed on the API keys page of your dashboard, where you can disconnect them.

Cursor, Claude Code or your own agent

Send an API key instead of signing in. Most apps read a config like this:

{
  "mcpServers": {
    "afriflux": {
      "url": "https://www.afriflux.xyz/mcp",
      "headers": {
        "Authorization": "Bearer af_test_YOUR_KEY"
      }
    }
  }
}
ToolWhat it doesCost
credits_balance
Check credit balance
View credit balanceFree
screen_wallet
Screen a wallet
Screen one addressFree if unmatched · 3 credits per matched label · 10 credits per matched operational label · 5 credits per matched freeze record
screen_wallets
Screen several wallets
Screen a batch of addresses. Up to 25 per call.Free if unmatched · 3 credits per matched label · 10 credits per matched operational label · 5 credits per matched freeze record

Test keys and test connections return the same sample answers as the sandbox, for free. A key needs access to each tool's API. Larger batches stay on the HTTP API.

Reference

Authentication

Send API keys as Bearer credentials. Test keys always use the sandbox; live keys are available as soon as you create your account. A key can only read the scopes selected for it.

Always call https://api.afriflux.xyz exactly as written. Other addresses redirect, and most HTTP clients drop the Authorization header when they follow a redirect, which shows up as a missing_key error.

Authorization: Bearer af_live_YOUR_KEY

Sandbox

Test-key calls never use credits. Every API that charges credits returns fixed sample responses, the same ones you can run from its playground. Free reference lists return the same public data as a live key. Force an error response with a scenario header.

X-AfriFlux-Sandbox-Scenario: server_error

Credits and limits

  • One credit balance covers every API. Each call costs a set number of credits, shown next to every endpoint here and on the pricing page.
  • Invalid input is never billed.
  • Use an Idempotency-Key on supported write or batch requests.
  • Rate and plan limits apply across all keys on an account.
  • Credit and pricing information is returned in X-AfriFlux-* headers.

Errors

Every error has the same shape. Branch on error.code, show error.message to a person, and quote request_id when you contact us. Failed calls made with your key also appear in your dashboard's request log.

{
  "error": {
    "code": "invalid_key",
    "message": "The key was not recognised. Check for a typo, or that a test key is not being used as a live one."
  },
  "request_id": "req_5f0c2a9d41b84c0e9a7d3e1b6c2f8a90"
}
StatusCodeWhat it means and what to do
400invalid_requestThe request did not match what this endpoint expects. Compare it with the example in the docs.
400invalid_addressThe address is not valid for that chain.
400unsupported_chainThat chain is not supported. The coverage endpoint lists the chains we cover.
400unknown_metricThat metric does not exist. The docs list the metrics you can ask for.
400invalid_rangeThe date range is not valid for this endpoint.
400invalid_idempotency_keyThe Idempotency-Key header is not valid.
401missing_keyNo API key was sent. Add an Authorization: Bearer header.
401invalid_keyThe key was not recognised. Check for a typo, or that a test key is not being used as a live one.
401revoked_keyThis key was revoked. Create a new one on the API keys page.
401expired_keyThis key has passed its expiry date. Create a new one on the API keys page.
402insufficient_creditsNot enough credits for this request. Add credits on the Billing page.
403missing_scopeThis key does not have access to this API. Edit the key's access on the API keys page.
403ip_not_allowedThis live key only accepts requests from its allowed IP addresses. Edit the key or call from an allowed address.
403live_access_suspendedLive access is paused for this account. Test keys still work.
403live_access_pendingLive keys are turned on once we have reviewed this account. Test keys work now.
403account_inactiveThis API account is not active.
403paid_access_requiredThis API uses AfriFlux's private data, which needs a paid account. Buy credits or choose a plan on the Billing page. Free signup credits work on every other API.
404not_foundNothing was found for what you asked for.
404endpoint_not_availableThis endpoint is not available right now.
413batch_limit_exceededToo many items in one request for your plan. Split it into smaller batches.
429rate_limit_exceededToo many requests in one second for your plan. Wait a moment and retry.
429daily_unique_address_limit_exceededYou reached today's limit of unique addresses. It resets at 00:00 UTC.
429too_many_attemptsToo many requests with unknown API keys came from your address. Check the key, then retry after the Retry-After time.
500internal_errorSomething went wrong on our side. Any credits charged for this call are refunded.
503pricing_unavailableSomething went wrong on our side. Nothing was charged.
503freeze_data_unavailableFreeze records could not be read just now. Nothing was charged. Try again in a minute.

Retry 429 after the Retry-After header and 500 or 503 after a short wait. Other errors will fail the same way until the request changes.

Versions and changes

  • The version is in the address: /v1. Within a version we do not remove an endpoint or a field, rename one, or change what a field means.
  • We do add things within a version: new endpoints, new optional parameters and new fields in a response. Write your code to ignore fields it does not know.
  • A change that would break your code ships as a new version at a new address. The old version keeps working beside it.
  • Before we switch off a version we give at least 90 days' notice, by email to account owners and on the changelog.
  • Prices are on the pricing page, and every response says what it cost. Price changes are posted on the changelog. Credits you have already bought are not affected.

Reliability and support

  • The status page shows whether the API is up now and its record over the last 30 days. We check it every 10 minutes and are alerted when it fails.
  • Wallet labels are refreshed every day. Each label carries the date we last saw it, and valid_until says how long you may treat an answer as current.
  • Every response has a request ID, and a Server-Timing header with the time our server spent on it. Include the request ID when you write to us.
  • Questions and problems: motolayahaya@gmail.com.

Storage and licensing

Standard access permits internal/product enrichment, individual display, caching until valid_until, and historical audit records. It prohibits raw redistribution, resale, a competing label API or database, systematic enumeration, model training, key sharing, and serving expired labels as current. Responses include a customer-specific license fingerprint. Attributions are analytical signals, not proof of legal ownership, sanctions or criminal conduct.