API: getting started

Being released

The money rails described here are built and tested, and are being rolled out. Until a rail is switched on for the exchange, invoices are paid by bank transfer or mobile money and recorded by Finance, as today.

The exchange's web app is built on a JSON API, and everything the app does can be done through it.

Base URL	https://apiexchange.yeshara.network
Version	Every path starts with /api/v1/
Format	JSON in and out, UTF-8
Authentication	A bearer token from signing in

Signing in

POST /api/v1/auth/login
Content-Type: application/json

{ "email": "you@example.com", "password": "…" }

{
  "user": { "id": "USR-0007", "name": "Finance desk", "roles": ["Finance"], "status": "Active" },
  "token": "agt_sess_…",
  "expiresAt": "2026-12-02T09:00:00.000Z"
}

Send the token on every request:

GET /api/v1/invoices
Authorization: Bearer agt_sess_…

• A session lasts 30 days, or until POST /api/v1/auth/logout ends it.
• GET /api/v1/auth/me returns the signed-in user and their roles.
• A wrong email and a wrong password get the same answer. Repeated wrong passwords are refused for a while with 429 too_many_attempts and a Retry-After header.
• Changing your password (POST /api/v1/auth/password) ends every other session of yours.

Users are created by an admin; there is no self sign-up.

Who may do what

Reading needs any signed-in user. Writing needs a role the route accepts; an Admin holds every role. The rules are on Roles and sign-in, and each endpoint's role is listed on All endpoints. A write without the role is refused with 403 forbidden, which names the roles that would be accepted.

Conventions

• Money is in integer minor units: amountMinor: 154500_00 is 154,500.00 in the record's currency. Nothing is a decimal string or a float.
• Ids carry their kind: INV-0042 (invoice), ESC-0007 (escrow), TRF-0001 (transfer), WR-0012 (warehouse receipt), ORD-0005 (order), TRP-0003 (trip), PTY-0002 (party), CRD-0004 (card), CHD-0001 (cardholder). A malformed id is a 400, an unknown one a 404.
• Dates are YYYY-MM-DD; times are ISO 8601 in UTC.
• A payment out answers 202 Accepted with the transfer it opened: the money has not moved yet. See Money endpoints.

Open endpoints

These need no token:

Endpoint	What
GET /health	The API and its database answered, and which kind of ledger and of each rail is in use (none when off)
GET /api/v1/catalogue	The commodities and products the exchange trades
GET /api/v1/ledger	Which ledger the receipts are recorded on
GET /api/v1/receipts/WR-…	A warehouse receipt, for a bank or buyer verifying it
GET /api/v1/invoices/INV-…	A public invoice, with how to pay it
POST /api/v1/hooks/mamlaka/payments, /cards	Mamlaka callbacks; see Callbacks and webhooks