nigerian-reference-data-mcp

An MCP server that gives AI agents pay-per-call Nigerian reference data and validation — no API key, no account, no signup. Each paid call settles in USDC over x402 on Base or Polygon, so an agent can buy exactly what it needs, one call at a time.

Built for agents doing Nigerian onboarding, form validation, routing and fraud screening — the checks they currently cannot do, because the data is local.

Install

Add to any MCP host (Claude Desktop, Cursor, Hermes, and anything else speaking MCP):

{
  "mcpServers": {
    "nigerian-reference-data": {
      "command": "npx",
      "args": ["-y", "nigerian-reference-data-mcp"],
      "env": { "X402_PRIVATE_KEY": "0xYOUR_WALLET_KEY" }
    }
  }
}

X402_PRIVATE_KEY is optional. Set it and the server pays each x402 challenge automatically from that wallet (which needs USDC on Base or Polygon — the facilitator covers the gas, so no native token is required). Leave it out and paid tools return the live payment challenge instead of data, so your host can settle it however it likes. The free tool works either way.

If your wallet holds USDC on a chain other than Base, set X402_PREFER_NETWORKS to the chain you want to pay on, e.g. eip155:137 for Polygon. Without it the server pays on Base.

Related MCP server: boo-x402-mcp

Tools

Example — ask your agent: "Is 08031234567 a valid Nigerian number, and which network is it on?"

What it deliberately does not do

Format and reference validation only. No personal data is returned, no identity database is queried, and no account is confirmed to exist. Real NIN/BVN verification requires a NIMC-licensed partner and is a separate thing entirely.

HTTP API

The same endpoints are available directly over HTTP if you'd rather not use MCP:

• GET /v1/ng/phone/lookup?number=08031234567 — $0.003

• GET /v1/ng/bank/validate?bank_code=058&account_number=0123456789 — $0.003

• GET /v1/ng/identity/format?type=NIN&value=12345678901 — $0.002

• GET /v1/ng/states — free

An unpaid call returns 402 Payment Required with machine-readable terms in the PAYMENT-REQUIRED header. Manifest: /llms.txt, OpenAPI: /openapi.json.

Licence

MIT.