10KOBO DOCS

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…UseAccount needed?
an AI agent that pays peoplex402 (standard, NEAR)No. Just a NEAR wallet with USDC
an assistant in Claude or ChatGPTMCPNo
a backend that pays at volumeHTTP API with a keyYes, a key from us
a shop with no developerPayment links and widgetYes, a free 10kobo account
a shop with its own serverCheckout for developersYes, 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.

your-shop — pay-with-x402.ts
// 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 ...
TypeScriptUTF-8 · 33 lines

What happens on the wire:

your-shop — x402-flow.txt
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
JavaScriptUTF-8 · 11 lines
FieldMeaning
amount_nairaNaira the account receives, whole number
bank_nameThe bank as people say it: “OPay”, “GTBank”, “Access Bank”
account_number10 digits
pay_from“near” for the standard exact scheme
refund_toWhere USDC goes back if delivery fails (your NEAR account)
payer_name, payer_email, purposeRequired 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.

your-shop — pay-with-key.sh
# 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"
ShellUTF-8 · 15 lines

A payment looks like this. Keep id; it is also the receipt reference.

your-shop — payment.json
{  "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}
JSONUTF-8 · 15 lines

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 nothing
  • accept_quoteGives the exact USDC and the one-time address to send it to.Moves nothing
  • check_paymentFollows the payment and returns the receipt once the bank is paid.Read-only

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.

your-shop — 1-create-invoice.ts
// 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, ... }
TypeScriptUTF-8 · 11 lines
your-shop — 2-open-checkout.html
<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>
HTMLUTF-8 · 8 lines
your-shop — 3-confirm.ts
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);}
TypeScriptUTF-8 · 7 lines
CallWhat it does
POST /v1/merchant/invoicesMake an invoice: reference, and amount_naira or line_items. Optional note, due_date, return_url
GET /v1/merchant/invoices/:idRead an invoice and its status
POST /v1/merchant/invoices/:id/cancelCancel 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.

your-shop — verify-notice.ts
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.
TypeScriptUTF-8 · 13 lines
EventWhen
invoice.paidThe money arrived. Always sent, even after an earlier expired or cancelled
invoice.cancelledYou or the customer cancelled it
invoice.expiredNobody paid in time

A notice that does not get a 2xx answer is sent again later, with longer waits between tries.

Payment statuses

StatusMeaning
quotedPriced, nothing accepted yet. A quote expires after a few minutes.
awaiting_depositAccepted. Send pay_usdc to deposit_address before deposit_deadline.
processingThe USDC has arrived and is on its way to the bank partner.
payingThe bank partner is paying the naira.
paidThe naira is in the account. A receipt is attached.
expiredNothing arrived in time. Nothing was paid; ask for a new quote.
refundedDelivery failed and the USDC went back to refund_to. No naira was paid.
needs_supportSomething 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.

LimitAmount
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 key3 at once
Price checks from one address30 an hour
Accepted payments from one address10 an hour
With an API keyThe daily limit set for that key
Merchant keys per account3 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": "…" }.

CodeHTTPWhat to do
invalid_request400A field is missing or wrong. The message names it.
invalid_key401The API or merchant key is not valid.
key_required401Paying without a key is closed right now.
account_not_found404/422The bank has no account with that number.
below_minimum422Too small. The message gives the smallest amount.
over_payment_limit422More than one payment may be.
over_daily_limit422Over the day’s limit for this key.
over_wallet_limit422This wallet has reached its limit for today.
over_account_limit422This bank account has received its limit for today.
too_many_open429Several unpaid payments to this account are waiting. Finish one first.
too_many_requests429Slow down and try again later.
quote_expired410Ask for a new quote.
price_changed409The rate moved. Ask for a new quote.
reference_used409That invoice reference already exists with different details.
bank_unavailable503The bank partner is not answering. Try again soon.
unavailable503The 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.