> For the complete documentation index, see [llms.txt](https://docs.abapays.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.abapays.com/protocols/api.md).

# REST API

> Plain HTTP

The same settlement rail as x402, described as a plain OpenAPI 3.1 document for any HTTP client that isn't speaking MCP or A2A. One endpoint, Celo-only, machine-readable.

## POST /api/pay/x402

Settles a real-world bill payment. The caller pays in a supported Celo stablecoin; on confirmed settlement, AbaPay vends the underlying service and returns the result. Price is dynamic — it equals the live value of the bill, so there is no fixed catalog price for this resource.

### Request body

| Field             | Type   | Description                                                       |
| ----------------- | ------ | ----------------------------------------------------------------- |
| `serviceID`       | string | VTpass service identifier, e.g. "mtn", "ikeja-electric"           |
| `serviceCategory` | string | AIRTIME \| DATA \| ELECTRICITY \| CABLE \| BANK \| EDUCATION      |
| `network`         | string | Provider name, e.g. MTN, IKEJA-ELECTRIC, DSTV                     |
| `billersCode`     | string | Phone number, meter number, or smartcard/IUC number               |
| `nairaAmount`     | number | Bill amount in NGN — the source of truth for pricing              |
| `token`           | string | "USDC" or "USDT" — both implement EIP-3009 on Celo                |
| `blockchain`      | string | "CELO" — this rail is Celo-only                                   |
| `wallet_address`  | string | The paying wallet, cross-checked against the signed authorization |

### Responses

* **200 Settled** — bill vended, or queued for background processing.
* **402 Payment Required** — standard x402 challenge, see [x402](/protocols/x402.md).

200 response body:

```json
{
  "success": true,
  "status": "SUCCESS",
  "purchased_code": null,
  "units": null,
  "request_id": "req_...",
  "tx_hash": "0x91a3...4f2c"
}
```

### Try it

A GET or probing POST with no payment attached returns a valid 402 challenge — the endpoint is always live for discovery, no credential required to see the price.

```bash
curl -X POST https://www.abapays.com/api/pay/x402 \
  -H "Content-Type: application/json" \
  -d '{"serviceID":"mtn","serviceCategory":"AIRTIME","network":"MTN","billersCode":"08012345678","nairaAmount":1000,"token":"USDT","blockchain":"CELO","wallet_address":"0xYourAgentWallet"}'
```

Full machine-readable spec: [openapi.json](https://abapays.com/openapi.json).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.abapays.com/protocols/api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.