{"openapi":"3.1.0","info":{"title":"AfriFlux API","version":"1","summary":"AfriFlux developer APIs.","description":"Every API published through the AfriFlux catalog. Interactive documentation lives at https://www.afriflux.xyz/api-docs.","termsOfService":"https://www.afriflux.xyz/terms","license":{"name":"AfriFlux public terms","url":"https://www.afriflux.xyz/terms"}},"servers":[{"url":"https://www.afriflux.xyz"}],"tags":[{"name":"Wallet Labels API","description":"Resolve blockchain addresses to curated AfriFlux entity attributions without exposing internal evidence or clustering methodology."},{"name":"Market Data API","description":"Token and universe time series, snapshots, and DEX-implied reference-rate prints for African stablecoins, served from AfriFlux's daily snapshot pipeline."},{"name":"Reference Data API","description":"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."}],"paths":{"/v1/labels/{chain}/{address}":{"get":{"operationId":"wallet_labels_label_lookup","summary":"Look up one wallet label","description":"Returns the current attribution for an exact chain/address pair. Valid unmatched requests are billable.","tags":["Wallet Labels API"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Look up one wallet label","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"address":{"type":"string"},"chain":{"type":"string"},"matched":{"type":"boolean"},"entity":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"confidence":{"anyOf":[{"type":"string","enum":["medium","high"]},{"type":"null"}]},"as_of":{"anyOf":[{"type":"string"},{"type":"null"}]},"valid_until":{"type":"string"},"attribution_id":{"type":"string"},"license_fingerprint":{"type":"string"}},"required":["address","chain","matched","entity","category","role","confidence","as_of","valid_until","attribution_id","license_fingerprint"],"additionalProperties":false},"example":{"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..."}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Key lacks the required scope, or the account is inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded — retry after 1 second","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-afriflux-required-scope":"labels:read","parameters":[{"name":"chain","in":"path","required":true,"schema":{"type":"string"},"example":"base"},{"name":"address","in":"path","required":true,"schema":{"type":"string"},"example":"0x8894e0a0c962cb723c1976a4421c95949be2d4e3"}],"x-afriflux-billable-unit":"unique chain/address","x-afriflux-operation-code":"wallet_label_lookup"}},"/v1/labels/batch":{"post":{"operationId":"wallet_labels_label_batch","summary":"Look up a batch of wallet labels","description":"Deduplicates identical chain/address pairs before applying limits and credits.","tags":["Wallet Labels API"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Look up a batch of wallet labels","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string"},"chain":{"type":"string"},"matched":{"type":"boolean"},"entity":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"role":{"anyOf":[{"type":"string"},{"type":"null"}]},"confidence":{"anyOf":[{"type":"string","enum":["medium","high"]},{"type":"null"}]},"as_of":{"anyOf":[{"type":"string"},{"type":"null"}]},"valid_until":{"type":"string"},"attribution_id":{"type":"string"},"license_fingerprint":{"type":"string"}},"required":["address","chain","matched","entity","category","role","confidence","as_of","valid_until","attribution_id","license_fingerprint"],"additionalProperties":false}},"meta":{"type":"object","properties":{"unique_wallets":{"type":"number"},"credits_used":{"type":"number"}},"required":["unique_wallets","credits_used"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"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..."}]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Key lacks the required scope, or the account is inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded — retry after 1 second","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-afriflux-required-scope":"labels:read","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"wallets":{"minItems":1,"maxItems":2000,"type":"array","items":{"type":"object","properties":{"chain":{"type":"string","minLength":1,"maxLength":32},"address":{"type":"string","minLength":3,"maxLength":128}},"required":["chain","address"],"additionalProperties":false}}},"required":["wallets"],"additionalProperties":false},"example":{"wallets":[{"chain":"base","address":"0x8894e0a0c962cb723c1976a4421c95949be2d4e3"}]}}}},"x-afriflux-billable-unit":"unique chain/address","x-afriflux-operation-code":"wallet_label_lookup"}},"/v1/usage":{"get":{"operationId":"wallet_labels_usage","summary":"View account usage","description":"Returns recent billable usage and aggregate credit consumption for the month to date. Paginate with limit and cursor; pass format=csv to download.","tags":["Wallet Labels API"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"View account usage","content":{"application/json":{"schema":{"type":"object"},"example":{"credits_used":320,"requests":281,"period_start":"2026-07-01T00:00:00.000Z","recent":[],"next_cursor":null,"has_more":false,"limit":50}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Key lacks the required scope, or the account is inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded — retry after 1 second","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-afriflux-required-scope":"usage:read"}},"/v1/credits":{"get":{"operationId":"wallet_labels_credits","summary":"View credit balance and expiry","description":"Returns the unexpired balance and credit-lot expiry schedule.","tags":["Wallet Labels API"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"View credit balance and expiry","content":{"application/json":{"schema":{"type":"object"},"example":{"balance":4680,"lots":[{"remaining":4680,"expires_at":"2027-07-13T00:00:00.000Z"}]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Key lacks the required scope, or the account is inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded — retry after 1 second","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-afriflux-required-scope":"usage:read"}},"/v1/health":{"get":{"operationId":"wallet_labels_health","summary":"Check API availability","description":"Confirms that the published API product and serving database are available.","tags":["Wallet Labels API"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Check API availability","content":{"application/json":{"schema":{"type":"object"},"example":{"status":"ok","product":"wallet_labels","version":1}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Key lacks the required scope, or the account is inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded — retry after 1 second","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-afriflux-required-scope":"usage:read"}},"/v1/market-data/timeseries/{symbol}/{metric}":{"get":{"operationId":"market_data_timeseries","summary":"Query a token or universe time series","description":"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.","tags":["Market Data API"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Query a token or universe time series","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"resource":{"type":"string"},"symbol":{"anyOf":[{"type":"string"},{"type":"null"}]},"dimension":{"anyOf":[{"type":"string"},{"type":"null"}]},"measure":{"type":"string"},"grain":{"type":"string"},"entities":{"type":"array","items":{"type":"string"}},"series":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"object","properties":{"period":{"type":"string"},"value":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["period","value"],"additionalProperties":false}}},"first_period":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_period":{"anyOf":[{"type":"string"},{"type":"null"}]},"point_count":{"type":"number"},"truncated":{"type":"boolean"},"partial_last":{"type":"boolean"}},"required":["resource","symbol","dimension","measure","grain","entities","series","first_period","last_period","point_count","truncated","partial_last"],"additionalProperties":false},"meta":{"type":"object","properties":{"product":{"type":"string"},"version":{"type":"number"},"schema_version":{"type":"number"},"as_of":{"type":"string"},"as_of_data_day":{"type":"string"},"partial_last":{"type":"boolean"},"attribution_id":{"type":"string"},"license_fingerprint":{"type":"string"},"dataset_fingerprint":{"type":"string"}},"required":["product","version","schema_version","as_of","attribution_id","license_fingerprint","dataset_fingerprint"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false},"example":{"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"}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Key lacks the required scope, or the account is inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded — retry after 1 second","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-afriflux-required-scope":"market-data:read","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string"},"example":"cngn"},{"name":"metric","in":"path","required":true,"schema":{"type":"string"},"example":"chain:transfer_usd"}],"x-afriflux-billable-unit":"request","x-afriflux-operation-code":"timeseries_query"}},"/v1/market-data/tokens/{symbol}/snapshot":{"get":{"operationId":"market_data_token_snapshot","summary":"Latest snapshot for one token","description":"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).","tags":["Market Data API"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Latest snapshot for one token","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"slug":{"type":"string"},"symbol":{"type":"string"},"name":{"type":"string"},"issuer":{"type":"string"},"country":{"type":"string"},"currency":{"type":"string"},"decimals":{"type":"number"},"status":{"type":"string"},"launch_date":{"anyOf":[{"type":"string"},{"type":"null"}]},"chains":{"type":"array","items":{"type":"string"}},"supply":{"type":"object","properties":{"total_circulating":{"type":"number"},"mint_volume_usd_30d":{"type":"number"},"burn_volume_usd_30d":{"type":"number"}},"required":["total_circulating","mint_volume_usd_30d","burn_volume_usd_30d"],"additionalProperties":false},"supply_by_chain":{"type":"array","items":{"type":"object","properties":{"chain":{"type":"string"},"circulating_supply":{"type":"number"}},"required":["chain","circulating_supply"],"additionalProperties":false}},"lifetime":{"type":"object","properties":{"transfer_usd":{"type":"number"},"transfer_native":{"type":"number"},"dex_usd":{"type":"number"},"mint_usd":{"type":"number"},"burn_usd":{"type":"number"},"transfer_count":{"type":"number"},"dex_trade_count":{"type":"number"}},"required":["transfer_usd","transfer_native","dex_usd","mint_usd","burn_usd","transfer_count","dex_trade_count"],"additionalProperties":false},"holders":{"type":"object","properties":{"total_holders":{"type":"number"},"total_balance_usd":{"type":"number"}},"required":["total_holders","total_balance_usd"],"additionalProperties":false},"transfers_window":{"type":"object","properties":{"total_volume_usd":{"type":"number"},"total_transfer_count":{"type":"number"}},"required":["total_volume_usd","total_transfer_count"],"additionalProperties":false},"dex":{"type":"object","properties":{"total_lifetime_volume_usd":{"type":"number"},"total_lifetime_trades":{"type":"number"}},"required":["total_lifetime_volume_usd","total_lifetime_trades"],"additionalProperties":false},"tvl":{"type":"object","properties":{"tvl_usd":{"type":"number"},"pool_count":{"type":"number"},"snapshot_day":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["tvl_usd","pool_count","snapshot_day"],"additionalProperties":false},"corridor_count":{"type":"number"}},"required":["slug","symbol","name","issuer","country","currency","decimals","status","launch_date","chains","supply","supply_by_chain","lifetime","holders","transfers_window","dex","tvl","corridor_count"],"additionalProperties":false},"meta":{"type":"object","properties":{"product":{"type":"string"},"version":{"type":"number"},"schema_version":{"type":"number"},"as_of":{"type":"string"},"as_of_data_day":{"type":"string"},"partial_last":{"type":"boolean"},"attribution_id":{"type":"string"},"license_fingerprint":{"type":"string"},"dataset_fingerprint":{"type":"string"}},"required":["product","version","schema_version","as_of","attribution_id","license_fingerprint","dataset_fingerprint"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false},"example":{"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"}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Key lacks the required scope, or the account is inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded — retry after 1 second","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-afriflux-required-scope":"market-data:read","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string"},"example":"cngn"}],"x-afriflux-billable-unit":"request","x-afriflux-operation-code":"snapshot_query"}},"/v1/market-data/universe/snapshot":{"get":{"operationId":"market_data_universe_snapshot","summary":"Latest universe snapshot","description":"Headline KPIs, the token leaderboard, and per-chain totals for the whole tracked stablecoin universe in one call.","tags":["Market Data API"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Latest universe snapshot","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"headline_kpis":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"}},"token_leaderboard":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"chains":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}}},"required":["headline_kpis","token_leaderboard","chains"],"additionalProperties":false},"meta":{"type":"object","properties":{"product":{"type":"string"},"version":{"type":"number"},"schema_version":{"type":"number"},"as_of":{"type":"string"},"as_of_data_day":{"type":"string"},"partial_last":{"type":"boolean"},"attribution_id":{"type":"string"},"license_fingerprint":{"type":"string"},"dataset_fingerprint":{"type":"string"}},"required":["product","version","schema_version","as_of","attribution_id","license_fingerprint","dataset_fingerprint"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false},"example":{"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"}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Key lacks the required scope, or the account is inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded — retry after 1 second","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-afriflux-required-scope":"market-data:read","x-afriflux-billable-unit":"request","x-afriflux-operation-code":"snapshot_query"}},"/v1/market-data/rates/{symbol}/usd":{"get":{"operationId":"market_data_rate_print","summary":"DEX-implied USD reference rate (preview)","description":"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.","tags":["Market Data API"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"DEX-implied USD reference rate (preview)","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"object","properties":{"symbol":{"type":"string"},"quote":{"type":"string"},"preview":{"type":"boolean"},"methodology":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"window":{"type":"object","properties":{"first_day":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_day":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["first_day","last_day"],"additionalProperties":false},"days":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string"},"implied_price_usd":{"type":"number"},"volume_usd":{"type":"number"},"trade_count":{"type":"number"},"chains":{"type":"array","items":{"type":"string"}}},"required":["day","implied_price_usd","volume_usd","trade_count","chains"],"additionalProperties":false}}},"required":["symbol","quote","preview","methodology","window","days"],"additionalProperties":false},"meta":{"type":"object","properties":{"product":{"type":"string"},"version":{"type":"number"},"schema_version":{"type":"number"},"as_of":{"type":"string"},"as_of_data_day":{"type":"string"},"partial_last":{"type":"boolean"},"attribution_id":{"type":"string"},"license_fingerprint":{"type":"string"},"dataset_fingerprint":{"type":"string"}},"required":["product","version","schema_version","as_of","attribution_id","license_fingerprint","dataset_fingerprint"],"additionalProperties":false}},"required":["data","meta"],"additionalProperties":false},"example":{"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"}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Key lacks the required scope, or the account is inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded — retry after 1 second","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-afriflux-required-scope":"market-data:read","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string"},"example":"cngn"}],"x-afriflux-billable-unit":"request","x-afriflux-operation-code":"rate_print"}},"/v1/market-data/health":{"get":{"operationId":"market_data_health","summary":"Check API availability","description":"Confirms that the published API product is available and identifies the serving environment.","tags":["Market Data API"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Check API availability","content":{"application/json":{"schema":{"type":"object"},"example":{"status":"ok","product":"market_data","version":1,"environment":"live","time":"2026-08-23T04:12:00.000Z"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Key lacks the required scope, or the account is inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded — retry after 1 second","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-afriflux-required-scope":"market-data:read"}},"/v1/reference/status":{"get":{"operationId":"reference_status","summary":"Reference catalog status","description":"Entity counts, coverage-matrix symbols, and the as_of provenance stamp for the current snapshot.","tags":["Reference Data API"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Reference catalog status","content":{"application/json":{"schema":{"type":"object"},"example":{"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"}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Key lacks the required scope, or the account is inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded — retry after 1 second","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-afriflux-required-scope":"reference:read"}},"/v1/reference/tokens":{"get":{"operationId":"reference_tokens","summary":"List tracked tokens","description":"The token master: slug (canonical join key), symbol, issuer, country, currency, status, launch date, and chains. Filterable by status, chain, or country.","tags":["Reference Data API"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"List tracked tokens","content":{"application/json":{"schema":{"type":"object"},"example":{"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"}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Key lacks the required scope, or the account is inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded — retry after 1 second","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-afriflux-required-scope":"reference:read"}},"/v1/reference/tokens/{symbol}":{"get":{"operationId":"reference_token_detail","summary":"Resolve one token plus its coverage matrix","description":"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.","tags":["Reference Data API"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Resolve one token plus its coverage matrix","content":{"application/json":{"schema":{"type":"object"},"example":{"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"}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Key lacks the required scope, or the account is inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded — retry after 1 second","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-afriflux-required-scope":"reference:read","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string"},"example":"cngn"}]}},"/v1/reference/chains":{"get":{"operationId":"reference_chains","summary":"List supported chains","description":"Chain slugs and display names usable as entity filters across all products.","tags":["Reference Data API"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"List supported chains","content":{"application/json":{"schema":{"type":"object"},"example":{"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"}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Key lacks the required scope, or the account is inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded — retry after 1 second","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-afriflux-required-scope":"reference:read"}},"/v1/reference/venues":{"get":{"operationId":"reference_venues","summary":"List tracked venues","description":"The venue master: roles, chain and token presence, first/last active day, and lifetime USD flow. Filterable by chain or role.","tags":["Reference Data API"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"List tracked venues","content":{"application/json":{"schema":{"type":"object"},"example":{"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"}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Key lacks the required scope, or the account is inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded — retry after 1 second","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-afriflux-required-scope":"reference:read"}},"/v1/reference/corridors":{"get":{"operationId":"reference_corridors","summary":"List tracked corridors","description":"The corridor master: base/quote token pairs per chain and project with lifetime trade counts. The enumeration for corridor analytics.","tags":["Reference Data API"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"List tracked corridors","content":{"application/json":{"schema":{"type":"object"},"example":{"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"}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Key lacks the required scope, or the account is inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded — retry after 1 second","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-afriflux-required-scope":"reference:read"}},"/v1/reference/countries":{"get":{"operationId":"reference_countries","summary":"List covered countries","description":"Country slugs, names, and the tokens mapped to each currency area.","tags":["Reference Data API"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"List covered countries","content":{"application/json":{"schema":{"type":"object"},"example":{"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"}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Key lacks the required scope, or the account is inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded — retry after 1 second","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-afriflux-required-scope":"reference:read"}},"/v1/reference/coverage":{"get":{"operationId":"reference_coverage","summary":"Dataset coverage matrix","description":"Per-token, per-section dataset availability (live, in_progress, no_coverage_yet, not_applicable). Query this before consuming any metric to avoid silent gaps.","tags":["Reference Data API"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Dataset coverage matrix","content":{"application/json":{"schema":{"type":"object"},"example":{"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"}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Key lacks the required scope, or the account is inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded — retry after 1 second","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-afriflux-required-scope":"reference:read"}},"/v1/reference/health":{"get":{"operationId":"reference_health","summary":"Check API availability","description":"Confirms that the published API product is available and identifies the serving environment.","tags":["Reference Data API"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Check API availability","content":{"application/json":{"schema":{"type":"object"},"example":{"status":"ok","product":"reference","version":1,"environment":"live","time":"2026-08-23T04:12:00.000Z"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Key lacks the required scope, or the account is inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded — retry after 1 second","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-afriflux-required-scope":"reference:read"}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key with af_test_ or af_live_ prefix."}},"schemas":{"ApiError":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code"]},"request_id":{"type":"string"}},"required":["error"]}}}}