Guide
Conventions
Ids, pages, amounts, dates and errors: the rules every route follows.
Every route of the API follows the same rules for ids, pages, amounts, dates and errors.
Ids
Fence's ids are UUIDs (version 7): ordered by creation time, never changed, never reused. Fence deletes nothing. An asset you remove or a payment you withdraw keeps its id and gets a status.
Your own ids (asset_id, payment_id, asset_group_id) are compared exactly: G1 is not g1. Percent-encode them in a query: + as %2B, a space as %20.
Pages
A list answers one page and next_after. To read the next page, send it back as after, with the same filters. It is null on the last page. Most lists hold 100 items a page; some take a limit.
Lists are read live. Something that changes while you page can be missed, so read again from the first page when you need every item.
Amounts
Amounts are decimal text in the currency's unit, exactly as stored: "1054.99", never a number. Fence never adds amounts in different currencies together.
Dates and times
- A date is
YYYY-MM-DD, read in your asset program's time zone: a due date, the day a payment was made. - A time is in UTC to the microsecond and ends in
Z:2026-11-04T10:15:02.481920Z.
Errors
Answer | Meaning |
|---|---|
| Your batch was stored, but its shape is wrong. Read |
| No token, or an expired one. |
| The token lacks the scope the route needs, or your program grant is read only. |
| The program, or the thing you named, does not exist or is not yours. |
| The body is over 10 MiB. Nothing was stored; split the batch. |
| The body is not |
| A query or path value is wrong. The body names the problem. |
| Fence cannot reach its database. Try again shortly. |
The token check answers with a problem body (application/problem+json) that carries a code.
Nothing is overwritten
Your program's settings, payment plans, expected payments, allocations and asset states are kept in versions. The current value is one read away, and every earlier one is in a history route, such as GET …/assets/{id}/state/history.