For AI agents: the documentation index is at /llms.txt, and this page is available as Markdown at /institutional/migrate-to-cefi-paths.md.
Migrate to the /v1/cefi paths
CeFi REST v1.0.6 removes the legacy /api/v1/ path prefix. Every operation
is now served only under /v1/cefi/.
This release is a path move only. Response bodies, status codes, error formats, pagination behaviour and authentication are byte-for-byte what they were — update your base path and you are done.
A second, separate change landed in v1.0.10 on November 1, 2026: schema
version v2024_01_01 is removed. v2026_01_23 is now the default and the
only supported version, and it changes response shapes — see
Upgrading to v2026_01_23 below.
Are you affected?
You are affected if any request you send has a path beginning /api/v1/. Those
paths now return 404; there is no redirect and no grace period.
You are not affected if you were already calling /v1/cefi/ — the prefix
has been available since v1.0.5 (May 2026) and is unchanged.
Step 1 — change your base path
| Production | https://api.truex.co/v1/cefi/ |
| UAT (sandbox) | https://api.uat.truex.co/v1/cefi/ |
Most clients hold this in one constant. If yours does, that is the whole change.
Step 2 — map your paths
Every removed path and its replacement:
Service
| Removed | Use instead |
|---|---|
/api/v1/health | /v1/cefi/health |
/api/v1/versions | /v1/cefi/versions |
Assets and instruments
| Removed | Use instead |
|---|---|
/api/v1/assets | /v1/cefi/assets |
/api/v1/asset | /v1/cefi/assets |
/api/v1/instruments | /v1/cefi/instruments |
/api/v1/instrument | /v1/cefi/instruments |
Market data
| Removed | Use instead |
|---|---|
/api/v1/market/quote | /v1/cefi/market/quote |
/api/v1/markets/quote | /v1/cefi/markets/quote |
Clients
| Removed | Use instead |
|---|---|
/api/v1/clients | /v1/cefi/clients |
/api/v1/client | /v1/cefi/clients |
Orders
| Removed | Use instead |
|---|---|
/api/v1/orders | /v1/cefi/orders |
/api/v1/order | /v1/cefi/orders |
/api/v1/orders/{ref_id} | /v1/cefi/orders/{ref_id} |
/api/v1/order/{ref_id} | /v1/cefi/orders/{ref_id} |
/api/v1/orders/all | /v1/cefi/orders/all |
/api/v1/orders/active | /v1/cefi/orders/active |
/api/v1/order/active | /v1/cefi/orders/active |
/api/v1/orders/trade | /v1/cefi/orders/trade |
/api/v1/order/trade | /v1/cefi/orders/trade |
/api/v1/orders/activity | /v1/cefi/orders/activity |
/api/v1/order/activity | /v1/cefi/orders/activity |
/api/v1/orders/status/{ref_id} | /v1/cefi/orders/status/{ref_id} |
/api/v1/order/status/{ref_id} | /v1/cefi/orders/status/{ref_id} |
Balances
| Removed | Use instead |
|---|---|
/api/v1/balances | /v1/cefi/balances |
/api/v1/balance | /v1/cefi/balances |
/api/v1/balances/activity | /v1/cefi/balances/activity |
Transfers
| Removed | Use instead |
|---|---|
/api/v1/transfers | /v1/cefi/transfers |
/api/v1/transfer | /v1/cefi/transfers |
/api/v1/transfers/active | /v1/cefi/transfers/active |
/api/v1/transfer/active | /v1/cefi/transfers/active |
Singular forms are gone
The singular aliases (/asset, /instrument, /client, /order, /balance,
/transfer) were deprecated in v1.0.3 and are not carried over to /v1/cefi/.
Use the plural form — it is the same operation with the same response.
The one exception is market quotes, where /v1/cefi/market/quote and
/v1/cefi/markets/quote are both real endpoints with different behaviour. Keep
whichever one you were calling.
Step 3 — verify
curl -s https://api.truex.co/v1/cefi/healthThen grep your codebase for any remaining api/v1 — including config files,
deployment health checks, monitoring probes and integration test fixtures, not
just the client library.
What did not change in v1.0.6
Worth stating explicitly, because it is the most common wrong assumption about this release:
- The default schema version stayed
v2024_01_01until v1.0.10 removed it. A request with noX-Truex-Versionheader got exactly the response it got before. - Response bodies are unchanged. Raw arrays and objects, not envelopes.
- Pagination is unchanged. List reads that were unpaginated stay unpaginated.
- Error bodies are unchanged. RFC 7807 Problem Details, unwrapped.
- Authentication is unchanged, apart from signing the new path.
Upgrading to v2026_01_23
As of v1.0.10 (November 1, 2026), schema version v2024_01_01 is
removed:
v2026_01_23is the default, so a request sending noX-Truex-Versionheader gets the new response shapes.- A request that sends
X-Truex-Version: v2024_01_01— or any other version the API does not serve — is rejected with400 Bad Request.
A client still sending X-Truex-Version: v2024_01_01 (header or ?version=
query parameter) now fails every request. Drop it or replace it with
v2026_01_23.
The work below is independent of the path move above. Every client must be reading the envelope, following the cursor, and unwrapping errors.
Step 1 — adopt the new version
X-Truex-Version: v2026_01_23This is the default, so the header is optional, but pinning it explicitly means nothing about your client changes if the default ever moves again. The version may also be supplied as a query parameter if a header is inconvenient. The rest of this section is the client-side work the new format requires.
Step 2 — unwrap the envelope
Every response body is wrapped in data:
// v2024_01_01
[ { "...": "..." }, { "...": "..." } ]
// v2026_01_23
{
"data": [ { "...": "..." }, { "...": "..." } ],
"pagination": { "size": 10, "next_cursor": "1761955200000000000" }
}Step 3 — follow the cursor
This is the step that silently loses data if you skip it. Under v2024_01_01 a
list read returned everything. Under v2026_01_23 it returns at most size
records, and size defaults to 10.
A client that issues one request and treats the result as the complete set will read 10 orders and believe that is all of them. No error is raised.
| Page size parameter | ?size= |
| Default | 10 |
| Maximum | 100 (larger values are clamped, not rejected) |
| Cursor returned as | pagination.next_cursor |
| Cursor sent back as | ?timestamp= |
| End of results | next_cursor is null |
Note the asymmetry: the cursor comes back to you as next_cursor but goes
out as timestamp. It is a nanosecond-precision timestamp, and paging walks
backwards from it, so passing it through as an opaque string is correct — do not
parse, round, or reformat it.
def get_all(session, path, page_size=100):
results, cursor = [], None
while True:
params = {"size": page_size}
if cursor:
params["timestamp"] = cursor
body = session.get(path, params=params).json()
page = body["data"]
results.extend(page)
cursor = body["pagination"]["next_cursor"]
# An empty page alongside a cursor would loop forever — treat it as the end.
if not cursor or not page:
break
return resultsKeep the not page guard. An empty page returned together with a non-null
cursor is the one shape that turns this loop into an infinite one.
Step 4 — unwrap errors
The RFC 7807 Problem Details body is nested under an error key. The fields
inside it are unchanged.
// v2024_01_01
{ "type": "...", "title": "...", "status": 400, "detail": "..." }
// v2026_01_23
{ "error": { "type": "...", "title": "...", "status": 400, "detail": "..." } }Check your error handling for code that reads body["title"] or
body["detail"] directly — those move to body["error"]["title"] and
body["error"]["detail"]. HTTP status codes are unchanged, so any handling
keyed on the status code alone keeps working.
Step 5 — verify
GET /v1/cefi/versions reports the supported versions and the current default,
so you can assert on it from a test instead of tracking this page.
A good end-to-end check: create more than 10 of something, then read the list back and confirm you get all of them. That single test catches the pagination mistake, which is the one that fails quietly.
When a future version is deprecated, its responses carry RFC 8594
Deprecation and Sunset headers — worth logging so an expiring version shows
up in your own telemetry before it starts failing requests.
Reference
- Need help? Ask us on Discord, or email [email protected].
- See what changed in the changelog