Developer platform

AfriFlux API documentation

Build against every API currently published from the AfriFlux catalog. Start with deterministic sandbox fixtures, then move the same request to a live key.

Developer dashboard Quickstart Pricing

Getting started

Quickstart

Create an af_test_ key in the developer dashboard, then call any published endpoint below. Test keys are free and never touch production. Every API has a live playground on its own section — pick one, paste your key, and run a request from the browser.

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

Authentication

Send API keys as Bearer credentials. Test keys are permanently sandbox-routed; live keys are available as soon as you create your account. Keys can only read selected scopes.

Authorization: Bearer af_live_YOUR_KEY

Synthetic sandbox

Test keys are sandbox-routed: calls never query production data or consume credits. Each API ships deterministic fixtures you can run from its playground below. Force error responses with a scenario header.

Simulated 500 header
X-AfriFlux-Sandbox-Scenario: server_error

APIs

Wallet Labels API Market Data API Reference Data API

Wallet Labels API

v1See rates

Resolve a chain and wallet address to a curated AfriFlux entity attribution.

GET/v1/labels/{chain}/{address}Billable: unique chain/address

Look up one wallet label

Returns the current attribution for an exact chain/address pair. Valid unmatched requests are billable.

Example response

{
  "address": "0x8894e0a0c962cb723c1976a4421c95949be2d4e3",
  "chain": "base",
  "matched": true,
  "entity": "Binance",
  "category": "exchange",
  "role": "cex_bridge",
  "confidence": "high",
  "as_of": "2026-04-25",
  "valid_until": "2026-07-20T12:00:00.000Z",
  "attribution_id": "attr_01J...",
  "license_fingerprint": "afl_9dc8..."
}

POST/v1/labels/batchBillable: unique chain/address

Look up a batch of wallet labels

Deduplicates identical chain/address pairs before applying limits and credits.

Request body

{
  "wallets": [
    {
      "chain": "base",
      "address": "0x8894e0a0c962cb723c1976a4421c95949be2d4e3"
    }
  ]
}

Example response

{
  "data": [
    {
      "address": "0x8894e0a0c962cb723c1976a4421c95949be2d4e3",
      "chain": "base",
      "matched": true,
      "entity": "Binance",
      "category": "exchange",
      "role": "cex_bridge",
      "confidence": "high",
      "as_of": "2026-04-25",
      "valid_until": "2026-07-20T12:00:00.000Z",
      "attribution_id": "attr_01J...",
      "license_fingerprint": "afl_9dc8..."
    }
  ]
}

GET/v1/usage

View account usage

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

Example response

{
  "credits_used": 320,
  "requests": 281,
  "period_start": "2026-07-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.

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.

Example response

{
  "status": "ok",
  "product": "wallet_labels",
  "version": 1
}

Playground

Run real requests against the synthetic sandbox — no terminal, no setup. Paste an af_test_ key from your dashboard; it stays in this tab and is never sent anywhere except the API. Live keys are rejected here.

Market Data API

v1See rates

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}Billable: request

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.

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}/snapshotBillable: request

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).

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/snapshotBillable: request

Latest universe snapshot

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

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}/usdBillable: request

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.

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.

Example response

{
  "status": "ok",
  "product": "market_data",
  "version": 1,
  "environment": "live",
  "time": "2026-08-23T04:12:00.000Z"
}

Playground

Reference Data API

v1See rates

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.

Example response

{
  "data": {
    "counts": {
      "tokens": 7,
      "venues": 24,
      "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.

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.

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.

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.

Example response

{
  "data": {
    "venues": [
      {
        "slug": "binance",
        "name": "Binance",
        "roles": [
          "cex_bridge"
        ],
        "chains": [
          "base",
          "ethereum"
        ],
        "tokens": [
          "cNGN"
        ],
        "lifetime_total_usd": 41002118.75,
        "first_active_day": "2024-02-11",
        "last_active_day": "2026-08-22"
      }
    ]
  },
  "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.

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.

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.

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.

Example response

{
  "status": "ok",
  "product": "reference",
  "version": 1,
  "environment": "live",
  "time": "2026-08-23T04:12:00.000Z"
}

Playground

Reference

Credits and limits

Credits used = operation weight × billable quantity. See the generated rate table for each endpoint.
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

400Invalid request, chain or address

401Missing, invalid, revoked or expired key

402Insufficient credits

403Scope, account or live-access restriction

404API is not published

413Batch limit exceeded

429RPS or daily unique limit exceeded

500Internal error; charged usage is refunded

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.