# nTZS Partner API

> Programmable Tanzanian shilling payments on Base — collections, disbursements, wallets, bill and till payments, and USDC settlement. Every endpoint authenticates with a partner API key.

Read [/llms-full.txt](https://www.ntzs.co.tz/llms-full.txt) for the whole documentation in one file, or [/openapi.json](https://www.ntzs.co.tz/openapi.json) for the machine-readable contract.

## Docs

- [Full documentation](https://www.ntzs.co.tz/llms-full.txt): every capability, rule, recipe, endpoint and error code in one file.
- [OpenAPI 3.1 spec](https://www.ntzs.co.tz/openapi.json): request and response schemas for every endpoint. Generate a client from this.
- [Developer portal](https://www.ntzs.co.tz/developers): the same material as a browsable site.

## Before you write code

- **Capabilities gate endpoints.** Your key is granted a set (`wallets`, `collections`, `disbursements`, `transfers`, `treasury`, `swap`, `ramp`, `biashara`, `wakala`); anything outside it returns 403.
- **Quotes are mandatory** for withdrawals, spend and ramp. Never recompute a fee client-side.
- **Errors come in three shapes.** Branch on `code ?? error`, not `error` alone.
- **Send an `Idempotency-Key`** on anything that moves money.
- **Amounts are whole shillings**, always integers.
- **Start in test mode.** `POST /api/v1/testmode/advance` settles pending transactions on demand, so you can close the write-run-correct loop without waiting on a rail.

## Optional

- [Error reference](https://www.ntzs.co.tz/developers#errors): the same catalogue with retry semantics.
- [Webhooks](https://www.ntzs.co.tz/developers#webhooks): signed event delivery.