AfriFlux API documentation

Quickstart

Create an af_test_ key in the developer dashboard, then call the same routes used in production.

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

Send API keys as Bearer credentials. Test keys are permanently sandbox-routed; live keys require an active, approved account. Keys can only read selected scopes.

Authorization: Bearer af_live_YOUR_KEY

Sandbox calls never query production labels or consume credits. The Base address below is a deterministic match; any other valid address is unmatched.

Matched fixture
base / 0x0000000000000000000000000000000000000001

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

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

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

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

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

const response = await fetch(API + "/v1/labels/batch", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.AFRIFLUX_API_KEY,
    "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({ wallets: [{ chain: "base", address: "0x..." }] })
});
const labels = await response.json();

import os, requests
response = requests.post(
    API + "/v1/labels/batch",
    headers={"Authorization": f"Bearer {os.environ['AFRIFLUX_API_KEY']}"},
    json={"wallets": [{"chain": "base", "address": "0x..."}]},
    timeout=30,
)
response.raise_for_status()

{
  "credits_used": 320,
  "requests": 281,
  "period_start": "2026-07-01T00:00:00.000Z"
}

{
  "balance": 4680,
  "lots": [
    {
      "remaining": 4680,
      "expires_at": "2027-07-13T00:00:00.000Z"
    }
  ]
}

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

Credits, caching and limits

• Credits used = operation weight × unique billable quantity.
• Valid unmatched lookups consume credits; invalid input does not.
• Batch duplicates are billed once and retries can use an Idempotency-Key.
• Matched results are valid for seven days; unmatched results for 24 hours. Repeats during that window are not charged again.
• RPS, batch and daily unique-address limits apply across all account keys.
• Credit and pricing information is returned in X-AfriFlux-* headers.

Errors

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.