Pay any Nigerian bank account with USDC
Agents, apps and shops send USDC from Base, NEAR, Solana and more than ten other networks. 10kobo pays naira into the bank account, usually in under a minute. Shops can also take payment by bank transfer or crypto with a link or a checkout widget.
Getting started
Pick the way that fits what you are building. Reading these docs needs no account.
| If you are building… | Use | Account needed? |
|---|---|---|
| an AI agent that pays people | x402 (standard, NEAR) | No. Just a NEAR wallet with USDC |
| an assistant in Claude or ChatGPT | MCP | No |
| a backend that pays at volume | HTTP API with a key | Yes, a key from us |
| a shop with no developer | Payment links and widget | Yes, a free 10kobo account |
| a shop with its own server | Checkout for developers | Yes, a merchant key from Settings |
Base address for every request: https://api.10kobo.xyz. Requests and answers are JSON. Amounts in naira are whole numbers (5000 is ₦5,000); USDC amounts are strings with six decimals.
Every quote shows the account holder’s name from the bank before any money moves, so your code or agent can stop if the name does not match.
x402 for AI agents
10kobo speaks the x402 standard (version 2, scheme exact on near:mainnet). Any x402 client can pay a Nigerian bank account with no API key and no sign-up.
// npm install @x402/core @x402/fetch @x402/nearimport { x402Client } from '@x402/core/client';import { wrapFetchWithPayment } from '@x402/fetch';import { createClientNearSigner } from '@x402/near';import { ExactNearScheme } from '@x402/near/exact/client';// The agent's NEAR account. It needs USDC, and no NEAR for gas: 10kobo pays the gas.const client = new x402Client();client.register('near:*', new ExactNearScheme(createClientNearSigner({ accountId: process.env.NEAR_ACCOUNT_ID, secretKey: process.env.NEAR_PRIVATE_KEY,})));client.setSpendControls({ maxAmountPerPayment: '$50' }); // the client refuses more than $1 unless you raise itconst fetchWithPayment = wrapFetchWithPayment(fetch, client);const res = await fetchWithPayment('https://api.10kobo.xyz/v1/agent/x402/pay', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ amount_naira: 5000, bank_name: 'OPay', account_number: '0123456789', pay_from: 'near', refund_to: process.env.NEAR_ACCOUNT_ID, payer_name: 'Acme procurement agent', payer_email: 'agent@acme.com', purpose: 'Invoice 1042, office supplies', }),});const { settlement, payment } = await res.json();console.log(res.status, payment.status, payment.account_name); // 200 processing ...What happens on the wire:
POST /v1/agent/x402/pay (no payment yet)← 402 Payment Required PAYMENT-REQUIRED: { accepts: [{ scheme: "exact", network: "near:mainnet", amount: "1010137", asset: <USDC on NEAR>, payTo: <one-time account> }] } body.payment: { account_name: "ADA OKAFOR", amount_naira: 5000, status: "awaiting_deposit" }POST /v1/agent/x402/pay (same request again) PAYMENT-SIGNATURE: <signed USDC transfer>← 200 OK PAYMENT-RESPONSE: { success: true, transaction: <NEAR tx>, network: "near:mainnet" } body.payment: { status: "processing" } → "paid" when the bank confirms| Field | Meaning |
|---|---|
| amount_naira | Naira the account receives, whole number |
| bank_name | The bank as people say it: “OPay”, “GTBank”, “Access Bank” |
| account_number | 10 digits |
| pay_from | “near” for the standard exact scheme |
| refund_to | Where USDC goes back if delivery fails (your NEAR account) |
| payer_name, payer_email, purpose | Required without a key, so every payment has a record |
The agent signs one USDC transfer; 10kobo checks it with the official x402 NEAR verifier, submits it and pays the gas. If the bank payout fails, the USDC returns to refund_to. Base, Arbitrum, Ethereum and Solana are offered in the same 402 through a draft NEAR Intents scheme; the standard exact scheme on those networks is coming.
HTTP API
Three calls, from any language. With a key you get your own daily limit and a CSV of every payment. Keys are issued by us: message @10koboPay on X.
# 1. Price it and see the account holder's name. Moves nothing.curl -X POST https://api.10kobo.xyz/v1/agent/quotes \ -H "authorization: Bearer $TENKOBO_KEY" -H 'content-type: application/json' \ -d '{"amount_naira":5000,"bank_name":"OPay","account_number":"0123456789","pay_from":"base","refund_to":"0xYourWallet"}'# 2. Accept it: get the exact USDC and a one-time deposit address. Safe to repeat.curl -X POST https://api.10kobo.xyz/v1/agent/payments \ -H "authorization: Bearer $TENKOBO_KEY" -H 'content-type: application/json' \ -d '{"quote_id":"<id from step 1>"}'# 3. Send pay_usdc to deposit_address from your wallet, then follow the payment.curl https://api.10kobo.xyz/v1/agent/payments/<id> -H "authorization: Bearer $TENKOBO_KEY"# All your payments as a spreadsheet.curl https://api.10kobo.xyz/v1/agent/payments.csv -H "authorization: Bearer $TENKOBO_KEY"A payment looks like this. Keep id; it is also the receipt reference.
{ "id": "7e612f7e-…", "status": "awaiting_deposit", "amount_naira": 5000, "amount": "₦5,000.00", "pay_usdc": "3.612480", "pay_from": "base", "bank_name": "OPay", "account_number": "****6789", "account_name": "ADA OKAFOR", "deposit_address": "0x…", "deposit_deadline": "2026-11-12T10:30:00.000Z", "transactions": [], "failure_reason": null}pay_from can be base, near, arbitrum, ethereum, solana, optimism, polygon, avalanche, bsc, gnosis, monad, sui, aptos, tron or ton. On Tron and TON you pay in USDT. Send exactly pay_usdc to deposit_address; it is used once.
MCP
Give Claude, ChatGPT or any MCP client the 10kobo tools. The assistant can price and set up payments; the money is always sent from your own wallet.
Connect an assistant
Let Claude or ChatGPT price and arrange naira payments. It can't move money: you send the USDC from your own wallet.
The hosted MCP link goes live soon.
Claude: Settings → Connectors → Add custom connector. Enter a name, paste the link as the MCP server URL, then Add.
ChatGPT: Developer mode → Add custom MCP server. Paste the link as the Server URL, choose No authentication, tick “I understand”, then Create.
What it can do
quote_naira_paymentPrices a naira payment and shows the name the bank holds for the account.Moves nothingaccept_quoteGives the exact USDC and the one-time address to send it to.Moves nothingcheck_paymentFollows the payment and returns the receipt once the bank is paid.Read-only
Payment links and the checkout widget
For shops and creators with no developer. Make a link in the 10kobo app and share it, or paste two lines into any website.
- Open the 10kobo app → Payment links and make a new link. Choose a fixed price or let customers type the amount (with a minimum).
- Choose where the money goes: your 10kobo wallet, a bank account, USDC on Base, or a NEAR account.
- Share the link, or press Copy checkout widget and paste it into your website.
<script src="https://10kobo.xyz/checkout.js"></script><!-- Copy the link ID from the 10kobo app: Payment links → your link → Copy checkout widget --><a href="https://10kobo.xyz/p/YOUR_LINK_ID" data-10kobo-link="YOUR_LINK_ID">Pay ₦3,500</a>Customers pay by bank transfer in naira or crypto from any supported network. Each customer gets their own invoice, and the link can be used again and again.
Checkout for developers
Your server sets the price, 10kobo takes the payment, your server confirms it. Get a merchant key in the 10kobo app under Settings → Developers.
// Server only. Never put the merchant key in a web page.const res = await fetch('https://api.10kobo.xyz/v1/merchant/invoices', { method: 'POST', headers: { authorization: 'Bearer ' + process.env.TENKOBO_MERCHANT_KEY, 'content-type': 'application/json' }, body: JSON.stringify({ reference: order.id, // your order ID; the same reference returns the same invoice line_items: [{ description: 'Jollof rice', amount_naira: 3500 }], return_url: 'https://yourshop.com/orders/' + order.id, }),});const invoice = await res.json(); // { id, status, amount_naira, reference, checkout_url, ... }<script src="https://10kobo.xyz/checkout.js"></script><script> // invoiceId comes from your server (the invoice you just made). TenKobo.open(invoiceId, { onPaid: () => refreshOrder(), // a hint only: confirm on your server onClose: ({ paid }) => { if (!paid) showRetry(); }, });</script>const res = await fetch('https://api.10kobo.xyz/v1/merchant/invoices/' + invoiceId, { headers: { authorization: 'Bearer ' + process.env.TENKOBO_MERCHANT_KEY },});const invoice = await res.json();if (invoice.status === 'paid' && invoice.reference === order.id && invoice.amount_naira === order.total) { await fulfilOnce(order.id);}| Call | What it does |
|---|---|
| POST /v1/merchant/invoices | Make an invoice: reference, and amount_naira or line_items. Optional note, due_date, return_url |
| GET /v1/merchant/invoices/:id | Read an invoice and its status |
| POST /v1/merchant/invoices/:id/cancel | Cancel an unpaid invoice |
In production, return_url and your webhook address must be public https addresses.
Webhooks
Add a webhook address to your merchant key and 10kobo tells your server when an invoice is paid, cancelled or expired.
import { createHmac, timingSafeEqual } from 'node:crypto';// 10kobo-signature: t=1762941000,v1=<hex>export function verify(rawBody: string, header: string, secret: string) { const parts = Object.fromEntries(header.split(',').map((p) => p.split('='))); const age = Math.abs(Date.now() / 1000 - Number(parts.t)); if (!parts.t || !parts.v1 || age > 300) return false; // older than 5 minutes: refuse const expected = createHmac('sha256', secret).update(parts.t + '.' + rawBody).digest('hex'); return expected.length === parts.v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));}// Body: { "id": "<event id>", "type": "invoice.paid", "created_at": "…", "data": { <the invoice> } }// Answer with any 2xx. Use the 10kobo-event-id header to skip a notice you already handled.| Event | When |
|---|---|
| invoice.paid | The money arrived. Always sent, even after an earlier expired or cancelled |
| invoice.cancelled | You or the customer cancelled it |
| invoice.expired | Nobody paid in time |
A notice that does not get a 2xx answer is sent again later, with longer waits between tries.
Payment statuses
| Status | Meaning |
|---|---|
| quoted | Priced, nothing accepted yet. A quote expires after a few minutes. |
| awaiting_deposit | Accepted. Send pay_usdc to deposit_address before deposit_deadline. |
| processing | The USDC has arrived and is on its way to the bank partner. |
| paying | The bank partner is paying the naira. |
| paid | The naira is in the account. A receipt is attached. |
| expired | Nothing arrived in time. Nothing was paid; ask for a new quote. |
| refunded | Delivery failed and the USDC went back to refund_to. No naira was paid. |
| needs_support | Something is being checked by a person. Do not pay again. |
Limits
Limits are checked in code, under a lock, before any money moves. They are not left to an AI.
| Limit | Amount |
|---|---|
| Each payment, no key (x402) | ₦50,000 |
| Each wallet a day, no key | ₦100,000 |
| Each bank account a day, no key | ₦100,000 |
| Unpaid payments open to one account, no key | 3 at once |
| Price checks from one address | 30 an hour |
| Accepted payments from one address | 10 an hour |
| With an API key | The daily limit set for that key |
| Merchant keys per account | 3 live keys, 50 invoices a day each |
Errors
Every refusal has the same shape, so code can act on it: { "code": "too_many_open", "message": "…" }.
| Code | HTTP | What to do |
|---|---|---|
| invalid_request | 400 | A field is missing or wrong. The message names it. |
| invalid_key | 401 | The API or merchant key is not valid. |
| key_required | 401 | Paying without a key is closed right now. |
| account_not_found | 404/422 | The bank has no account with that number. |
| below_minimum | 422 | Too small. The message gives the smallest amount. |
| over_payment_limit | 422 | More than one payment may be. |
| over_daily_limit | 422 | Over the day’s limit for this key. |
| over_wallet_limit | 422 | This wallet has reached its limit for today. |
| over_account_limit | 422 | This bank account has received its limit for today. |
| too_many_open | 429 | Several unpaid payments to this account are waiting. Finish one first. |
| too_many_requests | 429 | Slow down and try again later. |
| quote_expired | 410 | Ask for a new quote. |
| price_changed | 409 | The rate moved. Ask for a new quote. |
| reference_used | 409 | That invoice reference already exists with different details. |
| bank_unavailable | 503 | The bank partner is not answering. Try again soon. |
| unavailable | 503 | The API is paused. Nothing was charged. |
For AI agents: a plain-text version of these docs is at https://10kobo.xyz/llms.txt. Questions: @10koboPay.