Seven endpoints that answer questions about you rather than about what we sell: are we up, who is this key, how much money is left, where did it go, and how to put more in.
GET /health is the only unauthenticated route on this API and the only one subject to no rate limit at all. It exists so your monitoring can watch us without you putting a credential into a monitoring system.
It answers 503 — not a 200 with a sad body — when the database probe fails or exceeds 2 seconds. An uptime checker configured with nothing but a URL therefore does the right thing.
402 carrying your balance and the amount required.discount_bps here is your headline rate — the tier, or the override that supersedes it. The rate on any given plan can be lower, and the catalogue row is where you read that. Why they differ.Every movement is a row, newest first, and each row carries the balance it produced. The sequence number and that balance are allocated by the same statement that moved the money, which is why any window reconciles without a second query:
| kind | Sign | Raised by |
|---|---|---|
| deposit | positive | A deposit that was credited — a crypto invoice you paid, or a bank transfer we recorded. |
| purchase | negative | An accepted order. |
| refund | positive | Undelivered units on a failed or partial order. One row per order, at most. |
| adjustment | either | A manual correction. |
| payout | negative | A withdrawal. |
| chargeback | negative | A reversal. |
created_after on this endpoint is inclusive. On /orders and /esims the same parameter is exclusive. That inconsistency is real, it is not going to be fixed silently, and it is written here so it does not become an off-by-one in your reconciliation.
Three routes. POST /deposits opens a cryptocurrency invoice, GET /deposits is your funding history, and GET /deposits/{id}is the answer to “I lost the invoice link”. This is the only rail on the API that makes the balance go up, and the only one whose effect you cannot undo.
POST /deposits answers 201, not the order endpoint’s 202, and the difference is the point: a 202 there means “we have your money and are provisioning”, while here nothing is in flight. What comes back is an invoice. The deposit is pending, your float is untouched, and the credit happens when the cryptocurrency settles and our payment provider calls us back. Amounts are whole dollars, $100 to $10,000 — the ceiling bounds one fat-finger rather than how much float you may hold, and two invoices are always available for more.
It is also the one write on this surface that takes no Idempotency-Key. A repeated POST mints a second invoice, which costs a row and nothing else: an unpaid invoice is not a charge, and two invoices credit twice only if you pay both — at which point you have sent twice the money and both credits are correct. Where the key does matter.
credited_cents greater than requested_cents is an ordinary response and not an error. Reconcile against credited_cents; the invoiced figure is what you asked for, not what you have.pending until the amount is final. A settlement that reports a readable zero credits nothing and raises a review on our side.refunded, and nothing will ever re-drive it — unlike cancelled, which stays claimable because crypto broadcast before an invoice lapsed and confirmed after it is ordinary. Money returned after we credited it does not reverse automatically: the float stays where it is, possibly already spent on profiles, and a person reconciles it. That is the one behaviour here worth knowing before it happens.A credited deposit writes a deposit row on the statement, and ledger_entry_id on the deposit is the join back to it. What deposits look like when you go live.
The only route on this API that takes no key and is subject to no rate limit. It exists so your monitoring can watch us without you embedding a credential in a monitoring system.
It answers 503 — not 200 with a sad body — when the database probe fails or takes longer than two seconds, so an uptime checker configured with nothing but a URL still does the right thing.
Read fresh from the database on every call, never from the cached principal — so it is the authoritative answer to “which key is this and is it live”.
mode is a property of the KEY, never of the account and never of the request. No header, query flag or body field can change it.
rate_limits is computed live from your band. It is the machine-readable form of the rate-limit page and it moves with your tier without us redeploying anything, so read it rather than hard-coding the table.
Deliberately un-cached: read fresh on every call, because it is the number a checkout decides on.
A sandbox key reports the sandbox float instead. Same field, same shape — only the money is imaginary.
The statement is the books. seq and balance_after_cents are allocated by the same statement that moved the money, so any window reconciles by construction: the sum of amount_cents over a page equals the difference of the balances at its ends.
A sandbox key always receives an empty page. Sandbox spend moves the sandbox float and writes no statement row at all, because the ledger has no mode column and a sandbox row would break the invariant an hourly job checks. The practical consequence is worth planning for: you cannot exercise statement-rendering code in sandbox.
| Name | Type | Rules |
|---|---|---|
| kind | enum | Filter by movement type.One of: deposit, purchase, refund, adjustment, payout, chargeback |
| created_after | ISO 8601 | INCLUSIVE — created_at >= value. Note this differs from /orders and /esims, where the same parameter is exclusive. |
| created_before | ISO 8601 | Exclusive — created_at < value. |
| limit | integer | Page size.1–200Default 50 |
| cursor | string | Opaque. Pass back next_cursor from the previous page, or omit it to start again. A malformed cursor is a 400 naming cursor, never a silent first page.≤ 512 characters |
The only route that makes the balance go UP, and the only one whose answer is not something that has happened. It creates an INVOICE: the deposit is pending, your float is untouched, and a deposit you open and walk away from has cost you a row and nothing else. The credit happens when the crypto settles and the provider calls us back, and only then.
It answers 201, not the orders endpoint's 202. A 202 there means "we have your money and are provisioning". Here nothing is in flight and nothing has been accepted — a resource was created and the money arrives if and when you pay it.
Whole dollars only, $100 to $10,000. The ceiling bounds one fat-finger, not how much float you may hold: two invoices are always available, and a bank transfer has a person on it and no ceiling at all.
Crypto, not cards. That is a decision rather than a gap, and the reason is on the page that renders this endpoint.
| Name | Type | Rules |
|---|---|---|
| amount_cents * | integer | Integer US cents, and a whole number of dollars — a multiple of 100. It is the amount you are choosing to send, not an amount you are reporting, and a round figure is what makes an invoice, a bank statement and a ledger row line up when somebody reconciles them by eye later. What actually arrives is credited to the cent regardless.$100–$10,000, in multiples of 100 cents |
Every deposit on the account, whichever rail it came in on: the crypto invoices this API mints, and the bank transfers a person records for you. method tells them apart.
The invoice link is on the list as well as on the single read, because "which of my deposits is still waiting to be paid, and where do I pay it" is the question this endpoint exists to answer.
A SANDBOX key always receives an empty page. That is consistent rather than missing: the sandbox float is not money, so it writes no deposit and no statement row — the same answer GET /ledger gives, for the same reason.
| Name | Type | Rules |
|---|---|---|
| status | enum | Filter by state. refunded is terminal. cancelled is NOT: an invoice that lapsed is still claimable, because crypto broadcast before it lapsed and confirmed after it is ordinary.One of: pending, credited, cancelled, refunded, reversed |
| limit | integer | Page size.1–200Default 50 |
| cursor | string | Opaque. Pass back next_cursor from the previous page, or omit it to start again. A malformed cursor is a 400 naming cursor, never a silent first page.≤ 512 characters |
The answer to "I lost the invoice link". Same shape as a row in the list, always scoped to your own account.
A SANDBOX key never resolves a deposit here: the sandbox writes none, so every well-formed dep_ id is 404 not_found. It is not "404 whatever you send" — the id is parsed first, so a wrong-kind id is the 400 described below and mode is never reached.
| Name | Type | Rules |
|---|---|---|
| id * | string | Must begin dep_. A wrong-kind id is a 400 naming id, not a 404. |