AfroTools API Documentation

Quickstart

Use the demo sandbox key below for deterministic development responses. Replace it with a dashboard key when your route needs authenticated production access.

Test keys return deterministic sandbox data. Keys beginning with afro_test_ are safe for documentation, demos, and local development.

curl -X POST "https://afrotools.com/api/v1/tax/paye" \
  -H "x-api-key: afro_test_demo123456789" \
  -H "Content-Type: application/json" \
  -d '{"country":"NG","grossMonthly":500000}'

Expected result: 200 OK with status, sandbox, and result.netMonthly.

Authentication

Send API keys with the x-api-key header. Query-string keys are accepted for quick testing, but headers are recommended for production.

# Header, recommended
x-api-key: afro_live_xxxxxxxxxxxxx

# Query parameter, quick testing only
?api_key=afro_live_xxxxxxxxxxxxx

Sandbox keys

afro_test_* keys return deterministic sandbox data and use sandbox free-tier limits.

Live keys

afro_live_* keys are created after sign-in and email verification in the API dashboard.

Do not expose production keys in browser JavaScript, public mobile apps, logs, screenshots, or support tickets. Use your backend as a proxy.

Rate limits

Tier	Daily limit	Monthly limit	Activation
Free API	100	3,000	Verified dashboard key
API Growth	10,000	300,000	Manual paid pilot
API Pro	100,000	3,000,000	Manual paid pilot
Enterprise/custom	Custom	Custom	Contracted access

Where a route exposes rate-limit headers, they use X-RateLimit-Limit and X-RateLimit-Remaining. Daily limits reset at midnight UTC.

Endpoint catalog

Method	Path	Use	Try first with
POST	`/api/v1/tax/paye`	Calculate PAYE salary tax for supported African countries.	Sandbox key
GET	`/api/v1/tax/rates`	Read PAYE and VAT reference rates by country.	Sandbox key
POST	`/api/v1/vat/calculate`	Add or extract VAT for supported countries.	Sandbox key
GET	`/api/v1/fx/rates`	Read latest and historical FX rates.	Sandbox key or live call
GET	`/api/v1/fuel/prices`	Read latest fuel prices by country or region.	Sandbox key or live call
GET	`/api/v1/rates/central-bank`	Read central-bank policy-rate and inflation reference data.	Sandbox key or live call
GET	`/api/v1/countries`	Read country metadata and available API products.	Sandbox key

PAYE calculate

POST/api/v1/tax/paye

Calculate gross-to-net or net-to-gross PAYE scenarios. Provide one salary input.

Field	Type	Required	Description
`country`	string	Yes	ISO alpha-2 country code such as `NG`, `KE`, or `ZA`.
`grossAnnual`	number	One salary input	Annual gross salary in local currency.
`grossMonthly`	number	One salary input	Monthly gross salary in local currency.
`netAnnual`	number	One salary input	Annual net salary for reverse calculation.
`netMonthly`	number	One salary input	Monthly net salary for reverse calculation.

curl -X POST "https://afrotools.com/api/v1/tax/paye" \
  -H "x-api-key: afro_test_demo123456789" \
  -H "Content-Type: application/json" \
  -d '{"country":"NG","grossMonthly":500000}'

Tax rates

GET/api/v1/tax/rates

Read PAYE and VAT reference data. Use country for a single market and type to filter to paye or vat.

curl "https://afrotools.com/api/v1/tax/rates?country=NG" \
  -H "x-api-key: afro_test_demo123456789"

VAT calculate

POST/api/v1/vat/calculate

Add VAT to an exclusive amount or extract VAT from an inclusive amount.

Field	Type	Required	Description
`country`	string	Yes	ISO alpha-2 country code.
`amount`	number	Yes	Amount in local currency.
`operation`	string	No	`add` or `extract`.
`customRate`	number	No	Optional override when a reduced or special rate applies.

curl -X POST "https://afrotools.com/api/v1/vat/calculate" \
  -H "x-api-key: afro_test_demo123456789" \
  -H "Content-Type: application/json" \
  -d '{"country":"NG","amount":1000,"operation":"add"}'

FX rates

GET/api/v1/fx/rates

Read current rates, single pairs, base conversions, and stored historical pairs where available.

Parameter	Type	Required	Description
`base`	string	No	Base currency, for example `USD`.
`target`	string	No	Target currency, for example `NGN`.
`amount`	number	No	Optional amount to convert.
`days`	number	No	Historical lookback when stored for the pair.

curl "https://afrotools.com/api/v1/fx/rates?base=USD&target=NGN"

Fuel prices

GET/api/v1/fuel/prices

Read petrol, diesel, and LPG prices where source coverage is available. Results include timestamps and source metadata.

curl "https://afrotools.com/api/v1/fuel/prices?country=NG"

Central-bank rates

GET/api/v1/rates/central-bank

Read policy rates, inflation reference data, central-bank names, and source fields by country or region.

curl "https://afrotools.com/api/v1/rates/central-bank?country=NG"

Countries

GET/api/v1/countries

Read country names, currencies, regions, population reference values, and available API products.

curl "https://afrotools.com/api/v1/countries?code=NG" \
  -H "x-api-key: afro_test_demo123456789"

Status and health

The status route returns the public API contract. The v1 health route returns category freshness and source metadata.

curl "https://afrotools.com/api/status"

curl "https://afrotools.com/api/v1/health"

Error format

Errors return JSON with an error field and, where available, a stable code.

{
  "error": "Invalid or missing API key",
  "code": "INVALID_API_KEY"
}

Status	Code	Meaning
400	`MISSING_REQUIRED_FIELD`	A required field or parameter is missing.
401	`INVALID_API_KEY`	The key is missing or invalid for the route.
404	`INVALID_COUNTRY`	The requested country, currency pair, or resource was not found.
429	`RATE_LIMIT_EXCEEDED`	The key or anonymous caller exceeded the allowed request limit.
500	`INTERNAL_ERROR`	The service could not complete the request.

Production path

Use sandbox keys for deterministic examples, Free API for dashboard-key testing, and API Growth or API Pro when a real product needs higher limits or support. Enterprise/custom is available for negotiated data scope, request limits, billing, and implementation review.

View pricing Request API pilot