11. Partner API reference ("Brokerage as a Service")

PM MTF Ltd, brokerage division (brand barriers). Sandbox base URL https://dev.brokerage.perpetuals.com.

Revision 28, 2026-10-24, and revision 27, 2026-10-21 (numbered before revision 28, which reserved the number, and published after it). Wire contract of the barriers Partner API, /partner/v1/*, served by the Order Router (Barriers.Router) behind the brokerage edge host. The design it implements is docs/design/partner-api-design-2026-09-02.md with the binding custody addendum docs/design/partner-api-custody-addendum-2026-09-02.md, the binding addendum of 2026-09-06 docs/design/partner-api-events-and-clients-2026-09-06.md (the life-cycle events, legal entities, professional clients) and the binding addendum of 2026-09-08 docs/design/partner-fix-gateway-2026-09-08.md (the FIX gateway); the code is normative (PartnerAuth.cs, Partners.cs, PartnerOnboarding.cs, PartnerEndpoints.cs, PartnerCustody.cs, PartnerWebhooks.cs, PartnerEvents.cs, Fix/*.cs, and for the app order commands of section 22 AppJwt.cs, AppJwks.cs, AppOrderIssuers.cs, AppOrderAuth.cs, AppOrders.cs, AppOrderCommands.cs and PartnerAppSettings.cs, and for the perpetual demo accounts of section 23 PartnerDemo.cs, DemoPerp*.cs and DemoPerpMath.cs); this document is the partner-facing description of it. The machine-readable OpenAPI 3.1 document is served at /partner/openapi.json by the router and at /openapi.json by the edge host. A self-contained integration guide that walks a partner's engineers (or their coding assistant) through every flow of this contract under PARTNER custody with a USD stablecoin, with complete request and response examples, is docs/12-partner-integration-guide.md. The FIX 4.4 gateway beside these routes (section 20) has its own rules of engagement, docs/14-partner-fix-gateway.md, served at /fix by the edge host beside this reference at /docs.

Contents

1. Overview and legal model
2. Environments and base path
3. Authentication
4. Envelope and error codes
5. Idempotency
6. Rate limits
7. Conventions
8. Partner-level reads
9. Onboarding under reliance
10. KYC maintenance and documents
11. MiFID appropriateness
12. Trading
13. Custody models
14. Money under BROKER custody
15. Collateral and settlement under PARTNER custody
16. Webhooks
17. Statements
18. Sandbox behaviour
19. Changelog
20. FIX gateway
21. Compatibility and change notice
22. App order commands
23. Perpetual demo accounts

1. Overview and legal model

The Partner API lets a licensed partner firm (a MiCA crypto-asset service provider, a MiFID investment firm, an electronic money institution, a credit institution or another obliged entity whose licence makes it eligible for third-party reliance) onboard its own end clients with us over an API and run a neobroker business under our MiFID licence, fully integrated into the partner's own application. The partner executes no order itself: every account, every order and the ledger record of every balance live with us. Whether the partner holds the client money is its custody model (section 13): under BROKER custody we hold it, under PARTNER custody the partner holds it under its own MiCA licence and reports every movement to us. A partner integrates over the REST routes and the webhooks of this document and, since revision 9, may enter orders and barrier requests over FIX 4.4 as well (section 20, docs/14-partner-fix-gateway.md): the same functions, sentences and codes on every transport. Since revision 21 your app may also send its users' perpetual orders, cancels, replacements and leverage changes to us DIRECTLY, each request carrying a short-lived token you sign for the signed-in user (section 22): the same pipelines, sentences and codes again, on a route family of its own that is not the Partner API's.

The legal model, in plain terms:

• The clients contract with PM MTF Ltd in its brokerage capacity (brand "barriers"). A client onboarded through the Partner API is our client: our terms, our order execution policy, our client categorisation, our complaints handling and our investor protection obligations apply exactly as they do to a client who registered on our portal. The partner is the distribution channel and the technical integrator.
• Order entry in your app (revision 21). On the reading of our lawyers that our operator relayed on 2026-10-07, operating your app is not reception and transmission of orders on your part provided (a) the parts of the app through which orders are entered are operated by PM MTF Ltd and (b) the app clearly tells the user so. Our compliance function records both on your go-live record before reliance is approved (the checklist of docs/12 10.6). The app order commands of section 22 carry the user's order from your app to us directly, so your backend is outside the path of every order the app enters; how the operation of the order-entry parts by PM MTF Ltd is shown (a module you build that our compliance reviews with you, or one we supply), the order-entry notice your app shows (served to your backend by a later revision, never on the app routes) and whether your server-side order entry stays open beside the app (22.10) are settled with our compliance function before go-live.
• Third-party reliance for customer due diligence. Where the partner holds a reliance-eligible licence and a reliance agreement is in place, we rely on the customer due diligence the partner performed under its own licence instead of repeating the identity verification ourselves. Reliance is granted per partner by our compliance function (relianceStatus APPROVED); onboarding is refused with code 4036 until then.
• Our responsibilities remain. Reliance never transfers the obligation: we remain responsible for the customer due diligence as if we had performed it. Consequently we keep every KYC package the partner sends exactly as received, we run our own sanctions and PEP screening on every client and on every identity change, we spot-check packages, and we may request the underlying verification documents at any time. The partner attests, with every package, that copies of the verification documents are available to us on request without delay (attestation.documentsAvailableOnRequest) and provides them through the documents route (section 10). We may reject reliance for a client (the client then has to be re-onboarded with fresh data or documents) and we may suspend or revoke reliance for the partner as a whole.
• The MiFID appropriateness assessment is ours and is not delegable. The partner collects the answers to OUR questionnaire in its own user interface and sends them to us; we score, decide and record the result, and only a result we hold as complete unlocks the MiFID product families (perpetuals, barrier contracts, staking swaps). The MiFID information blocks (account purpose, employment and finances, source of wealth, the MiFID declarations) are attested by the partner in the same way as the MiCA blocks.
• Scope. Natural persons (clientType NATURAL) and, since revision 8, legal entities (LEGAL, section 9.7). Every client is onboarded as RETAIL; a professional categorisation is requested AFTER onboarding on the client's behalf (section 11.6) and decided by our compliance function. Eligible counterparties have no path.
• Attribution. Every write the partner performs is recorded on our side with the partner code and the key prefix that performed it, and every money posting names the ledger actor partner:<CODE>. Our compliance and finance staff see the partner, its packages, its money flows and its webhook deliveries in our back office.
• Commission scheme (revision 10). The commission scheme agreed for the partner's clients applies to every client the partner onboards from its first order, request or take, set as the partner's default per product family by our operations; our operations may assign an individual client a different scheme; a change never re-prices an order already filled (its terms are frozen at its first fill).
• Custody model. A partner is configured as BROKER custody (the default: client money sits with us, deposits and withdrawals are confirmed by our finance desk, section 14) or PARTNER custody (the partner is the custodian of its clients' money under its own MiCA licence, a USD stablecoin valued 1:1 to USDC for margin; it reports collateral movements to us and settles every economic result with its client on its own rails, section 15). GET /partner/v1/me shows the model.
• One channel per client (revision 3, refined in revision 10). A client you onboard is serviced through your integration only: it holds no sign-in with us, no password can be set or reset for it and no second account can be opened on its e-mail address. Our own sign-in, forgot-password, verification-resend and registration routes answer such an address exactly as they answer any other address (a wrong-credentials refusal, an always-ok acknowledgement, a silent acceptance: nothing on the wire tells a caller that the address is yours) and, on a password-reset or registration attempt, the address holder receives a plain notice from us to use its provider's app (your firm is never named in it). Our direct client API with a session or key of such a client, the password-reset link, the development sign-in, our money desk and our back office keep refusing with 403 code 4038 PARTNER_CHANNEL ("This account is serviced by your provider."); our back office never pays such a client out through our own custody. Money moves only through the routes of sections 14 and 15, under the custody model of your partner record.

Nothing in this document is legal advice. The reliance agreement and our client terms govern; this reference describes the wire contract that implements them.

2. Environments and base path

Base path: /partner/v1. Every route in this document is relative to it unless written in full. The edge host also serves /openapi.json (this contract as OpenAPI 3.1), /docs (this reference rendered) and /healthz.

Since revision 21 the same host serves a second base path, /app/v1: the four app order commands your app sends directly to us (section 22, https://dev.brokerage.perpetuals.com/app/v1/orders on the development environment). It is not part of the Partner API: your partner key is never accepted there, it authenticates with the short-lived token you sign for the signed-in user, and none of its requests counts against the limits of section 6. Every route of this document outside section 22 stays under /partner/v1.

TLS is mandatory. Plain HTTP is not served.

3. Authentication

3.1 Keys

Every request carries a partner API key, issued by our operations team in the back office (section 9 of the design: an ADMIN issues keys, a key is shown ONCE at issue and only its SHA-256 is stored). Present it as a bearer token, or in the X-Partner-Key header:

Authorization: Bearer pbk_1f9c2d0b3e7a4c5d6e7f8091a2b3c4d5e6f7a8b9
X-Partner-Key: pbk_1f9c2d0b3e7a4c5d6e7f8091a2b3c4d5e6f7a8b9

• Keys start with pbk_. The first 10 characters (pbk_ plus six) are the key's display prefix; that prefix, never the key, appears in our audit lines ("placed by partner NEOBROKER1 key pbk_1f9c2d...") and in GET /partner/v1/me.
• A partner holds at most 10 active keys. Rotation is "issue the new key, move your integration, revoke the old key"; revocation is immediate and carries a reason on our side. A revoked or unknown key answers 401 code 4010.
• lastUsedAt on the key is refreshed at most once per minute.

3.2 Scopes

A READ key on a write route answers 403 code 4034 ("This partner key cannot use this endpoint.").

HEAD (revision 5) is accepted wherever GET is, on every route of this document and on /openapi.json: the edge answers it with the status and headers the GET would produce and no body (it reaches our router as a GET, so it counts against readPerMinute and appears in our logs as one). OPTIONS, PATCH and every other verb answer 404 code 4004 at the edge.

3.3 IP allowlist

A partner may be configured with a comma list of CIDR ranges (allowedCidrs, shown on GET /partner/v1/me). When the list is not empty, a request from an address outside it answers 401 code 4010 with exactly the answer an unknown key gets ("Sign in again.", revision 6); neither the list nor the fact that the key itself is valid is revealed to the caller. The source address is the connection's remote address; the X-Forwarded-For header is honoured only when the request reached the router from our own edge host, so a caller cannot forward its way onto an allowlist.

3.4 Partner status

The same partner status governs the app order commands of section 22: a SUSPENDED partner's tokens answer 403 code 4037 there too (decided only after the token's signature verified), a CLOSED partner's tokens the one 401 of 22.6.

Reliance status (NONE, REQUESTED, APPROVED, SUSPENDED, REVOKED) is separate: only APPROVED allows the onboarding writes (POST /clients, PUT /clients/{id}/kyc, PUT /clients/{id}/mifid); everything else keeps working for the clients already onboarded.

Close-only under the settlement tier (revision 10, section 15.7) is not a partner status but a settlement measure: while it holds, an opening order, a barrier request or accept and a staking take answer 403 code 4041 PARTNER_CLOSE_ONLY, everything else keeps working, GET /me is unchanged, and the measure lifts on our hourly check once the overdue items are settled and the unsettled sum is back under the agreed cap.

3.5 The app order token (revision 21)

The app order commands of section 22 do not use your partner key at all. Each request your app sends to /app/v1 carries Authorization: Bearer with a compact JWS your backend signed with ES256 for the user signed in to your app: the claims iss, aud, sub (our client uid exactly as issued, section 7), iat, exp (at most 5 minutes after iat) and jti, nothing else, verified against the key set you publish at the https URL our operations configure for you under four eyes. The token profile is 22.3, the key set and its rotation 22.4. A token never authenticates a /partner/v1 route, and a partner key never authenticates an /app/v1 route.

4. Envelope and error codes

Success answers are {"code": 0, "data": ...}. Error answers are

{"code": 4036, "msg": "KYC reliance is not approved for this partner. Onboarding is not available until compliance approves the reliance agreement.", "error": "KYC reliance is not approved for this partner. Onboarding is not available until compliance approves the reliance agreement.", "data": {"error": "RELIANCE_NOT_APPROVED"}}

code is a stable four-digit number, msg a sentence a person can read, error repeats the sentence (for older readers), and data carries the machine facts when there are any (the validation map, the missing blocks, the machine name of a partner refusal, the retake time).

A few routes delegate to client API routes that predate the envelope and keep that route's own body shape without the {code, data} wrapper; each such route is marked "(bare)" in its section. Their error answers still use the envelope above.

Over the FIX gateway (section 20, docs/14-partner-fix-gateway.md) a refusal carries the SAME code in the custom tag 9110 and the same sentence in Text(58): a Logon refused for an unknown key reads Sign in again. with 9110=4010, a suspended partner 9110=4037, a READ key 9110=4034, an unknown client on a business message 9110=4004, a router without the service 9110=5030, the TERMS re-consent gate on an opening order, an opening request or its accept 9110=4035 with the sentence in Text(58) and no 9118 (revision 10), the KID gate and the strict consent gate on an opening request 9110=4035 likewise (their sentences in Text(58)), a close-only partner's opening order, opening request or its accept 9110=4041 with the sentence in Text(58) (revision 10, section 15.7), and a NewOrderSingle(35=D) or OrderCancelRequest(35=F) of a partner whose server-side order entry is CLOSED 9110=4043 (revision 21, 22.10). One code table serves both transports.

5. Idempotency

Every POST and PUT that creates something or moves money honours the Idempotency-Key header (1 to 128 characters of your choosing, a UUID is fine): POST /clients, PUT /clients/{id}/kyc, POST .../documents, POST .../appropriateness, POST .../appropriateness/acknowledge, PUT .../mifid, POST .../rfq, POST .../rfq/{rfqId}/accept, POST .../barriers/{contractId}/close, POST .../staking/{offerId}/accept, POST .../orders, PUT .../leverage, POST .../statements, POST .../deposits, POST .../withdrawals, POST .../withdrawals/{rid}/cancel, POST .../collateral, POST /settlement/items/{itemId}/report, POST /settlement/report and POST /webhook/test (the document upload, the two appropriateness writes, the MiFID blocks, the statement generation and the webhook test since revision 6). The ONE creating write without the key is PUT /webhook, by design: every PUT rotates the signing secret and the secret is answered once, never stored for a replay; a retried PUT is a second rotation, so send it once and keep the answer.

• The first answer (status and body) is stored under (partner, key) and replayed BYTE FOR BYTE to a retry of the same request for 24 hours, whatever it was (a 201, a 400, a 409). A refusal that a later event cures is replayed too: after our compliance released a client's MiFID blocks (section 11), send the new PUT .../mifid with a NEW key, or the stored 409 answers again.
• ONE KEY PER SUBMISSION ATTEMPT on POST .../appropriateness (revision 15, 11.2). Mint the Idempotency-Key when the user taps Submit and store it before the call. Reuse it only to retry that same call after a timeout or a 5xx. After ANY refusal of this route (400, every 409, 429) the next submission is a new request and carries a NEW key: the stored refusal answers again for 24 hours under the old one, whatever cured it in the meantime (a re-read after a stale version, the end of the cooling period after a 429, the release of the compliance lock). The ONE exception is the 409 "still in progress" of the fourth bullet below, which is an answer about the KEY and not about the submission: retry it with the SAME key after 1 to 2 seconds. A key derived from your assessment record alone (the pattern the integration guide recommends for the trading writes) would replay a refusal to you for a day: derive it from the record AND a submission counter, for example appr:<recordId>:<submitSeq>.
• ONE exception to the stored refusal since revision 17 (11.2): the claim of a request that answers 409 code 4092 APPROPRIATENESS_VERSION_NOT_IN_FORCE (the announced version submitted a moment before its instant, a clock a little ahead of ours) is GIVEN BACK, so the SAME key may be sent again once the version is in force and scores then; every other refusal of the route is stored and replayed as above (revision 15's rule is unchanged).
• A reuse of the key for ANOTHER REQUEST answers 409 code 4092 ("This Idempotency-Key was already used for another request.") and executes nothing (revision 20): another method, another path, or ANOTHER BODY on the same path. Two bodies are the same request when they carry the same JSON content: the order of an object's members and the whitespace do not matter, every value does (another symbol, side, quantity, price, reference or amount, a member added or left out, a number written differently: 1, 1.0 and "1" are three requests); a body that is not JSON is compared byte for byte. So a retry your HTTP library serialised again replays, and a second order sent under the first order's key is refused instead of being answered with the first order's orderId. The 409 means the second request was NOT executed: send it under a new key. Whether the first request is still in flight or answered, the conflict answers at once, without the 5 second wait described below. Before revision 20 the comparison was the method and the path only, so a second request under a used key on the same path was answered with the FIRST request's stored answer and never executed; a key first used before the deployment of revision 20 keeps that comparison for the rest of its 24 hours.
• A malformed header (empty, over 128 characters) answers 400 code 4000.
• At most once (revision 4): the key is claimed BEFORE the request is executed, so two requests with the same key in flight at the same time (a timeout retry while the first one is still running) never both execute. The second one waits up to 5 seconds for the first one's answer and replays it; when the first one has not answered by then, the second one answers 409 code 4092 "A request with this Idempotency-Key is still in progress." and executes nothing: retry with the same key a little later and you get the stored answer. A request whose execution failed with an error on our side BEFORE it reached the trading venue gives the key back, so a retry runs it (a request that was waiting for it runs it instead).
• ONCE A REQUEST HAS REACHED THE TRADING VENUE its key is never given back (revision 19): POST .../orders, POST .../rfq, POST .../barriers/{contractId}/close and POST .../staking/{offerId}/accept mark their key just before the venue call. When our side fails after that point, the request answers its pending answer, the same one a venue transport failure gives (section 12): an order 200 with state SENT; a barrier request or close request 502 code 5020 with data.rfqId; a staking take 502 code 5020 with data {swapId, offerId, accepting: true}. That answer is stored and replayed under the key like any other, so a retry with the same key never reaches the venue a second time: read the object back for its outcome. When even that answer could not be stored, the key answers 409 code 4092 "still in progress" for up to five minutes and then replays the pending answer. Never re-send such a request under a NEW key before you read the state back.
• Without the header the request is not idempotent at the HTTP level; the money routes are idempotent on their business reference instead (next bullet) and the onboarding route on the partnerClientRef uniqueness.
• The business reference (revision 4): a POST .../deposits, POST .../withdrawals or POST .../collateral whose partnerRef you already filed for the SAME client answers the ORIGINAL notice, request or report with 200 (a REFUSED collateral report answers its original 409 code 4092 again) and writes nothing, whatever the rest of the body says. A partnerRef you spent on ANOTHER client answers 409 code 4092 ("This partnerRef was already used for another ..."). The reference is checked before the money gates, so a retry of a request the first call already reserved or booked is never refused for the funds the first call took. On POST .../deposits and POST .../withdrawals the reference is checked before every gate. On POST .../collateral the closed-account check and the verification gate come first (15.1) and the economic gates after the reference: a retry for a client who meets the source-of-wealth ask by then answers 403 code 4030, not the replay.
• The app order commands (revision 21, 22.7) keep their own rule: the Idempotency-Key is REQUIRED on each of the four routes, scoped to the client the token names (two users' equal keys never meet), and it is looked at only AFTER the token was accepted, so a request refused with 401, 403 4037, 429 or 503 by the authentication uses nothing under its key and the retry with a fresh token and the SAME key runs as a first attempt; nor are the answers of the key, size, media type and body shape checks stored, which run before the command (22.7).
• The perpetual demo (revision 28, 23.8) honours the key on its seven creating writes: POST .../demo/perp/account, POST .../demo/perp/orders, POST .../demo/perp/orders/{orderId}/replace, POST .../demo/perp/positions/{symbol}/close, PUT (and POST) .../demo/perp/leverage, POST .../demo/perp/top-up and POST .../demo/perp/reset, with the rules above; a demo write never reaches the venue and marks no point of no return, and the demo records the key on the row it wrote as well. Its DELETE routes and its preview take no key.

6. Rate limits

Two sliding 60 second windows per partner, configured per partner and shown on GET /partner/v1/me under limits: readPerMinute (default 600) counts GET and HEAD requests, tradePerMinute (default 120) counts everything else. Beyond the limit the router answers 429 code 4290 ("Too many requests. Please slow down and try again."). The limits are per partner, not per key.

The app order commands (revision 21, section 22) count against NEITHER window, and your FIX sessions' bucket is not touched by them either. They have windows of their own, sliding over 60 seconds (22.9): 120 commands per user, 300 requests per caller address before the token is read, and an app ceiling of 6,000 commands per partner. Each answers 429 code 4290 with the same sentence and a Retry-After header in whole seconds (at least 1), the wait until that window admits again.

The perpetual demo (revision 28, section 23) counts against NEITHER window either: every request under /partner/v1/clients/{clientId}/demo counts in two demo windows of your partner of their own, sliding over 60 seconds, 600 GET and HEAD requests and 120 other requests per minute (shown on GET /me demo.perp.limits), answered beyond with the same 429 code 4290. Live traffic never draws on the demo windows, and demo traffic never on yours.

7. Conventions

• Client identifiers (revision 25). We give every client two identifiers, both in the answer of POST /partner/v1/clients and on every client read, both permanent and one to one with the client: clientId, our numeric account number of the client (412 in the examples), and clientUid, the client's stable pseudonymous identifier, the one under which the client's orders reach the Kronos X MTF (BARR-00000412 in the examples). The third identifier, partnerClientRef, is yours. The clientUid is OPAQUE: store clientId and clientUid exactly as we return them, send the uid back exactly as we issued it, and never compute one from the other (neither the uid from the id nor the id from the uid). Its format is not part of this contract and may change for clients created later; a uid in this document is an example, not a format. Every /clients/{clientId} route accepts either our numeric clientId or the clientUid. The uid is accepted only EXACTLY as issued, the letter case and the digits as served: any other spelling (BARR-412, barr-00000412, one leading zero more or fewer) names no client and is refused like an unknown one, with 404 code 4004 ("Unknown client.") on a route, with a BusinessMessageReject(35=j) 380=1, Text(58) Unknown client. and 9110=4004 as the PartyID(448) of a FIX message (docs/14 section 2), and with the one 401 code 4010 ("Sign in again.") as the sub of an app order token (22.3). A client of another partner is refused the same way on each channel (404 code 4004 on a route, the 35=j on FIX, the one 401 as a token's sub). GET /clients/by-ref/{partnerClientRef} resolves your own reference. Every object that names a client carries clientId; most carry clientUid beside it, and the client reads, the onboarding and KYC revision answers, the verification view, the categorisation answers, the settlement items and the webhook delivery envelope (16.2) also carry your partnerClientRef (the rows of the delivery log, 16.1, carry clientId and clientUid only). The margin read (12.3) and the statement list rows (section 17) carry clientId only; the model of a single statement (GET .../statements/{sid}) names the client by clientId and by the uid as model.account.clientRef, which its PDF prints too: match that clientRef as served, like any uid. BARR- also begins references of ours that are NOT client identifiers: our order reference, the clOrdId BARR-{orderId} of an order (the order id unpadded, BARR-4185; 12.3), the clOrdId BARR-RFQ-{rfqId} of a barrier request (12.2), and the venue reference BARR-SWP-{swapId} of a staking swap take. Never send one of them where a client is named (a route's {clientId}, PartyID(448) on FIX, a token's sub): it is not a client identifier.
• Money travels as decimal strings in the currency's own scale ("1500.000000" USDC, "0.05000000" BTC). The client currencies are USDC (the cash currency, 6 places) and the asset currencies BTC, ETH (8 places), SOL, BNB, XRP, EUR, USD1 (6 places); GET /partner/v1/currencies is the registry. Since revision 10 each registry row carries valuationBasis: CASH on the cash currency, MARK on a currency valued at its market's mark, PAR on a currency our registry values at 1.000000 USDC per unit without a market price (no currency is PAR yet).
• Timestamps are Unix milliseconds UTC (1788310800000), except the webhook signature timestamp, which is Unix seconds.
• Paging is keyset: limit (1 to a per-route maximum) and before (the nextBefore of the previous page); answers carry hasMore and nextBefore (null on the last page).
• Dates in the KYC blocks are ISO 8601 calendar dates (YYYY-MM-DD), countries ISO 3166-1 alpha-2, block field names snake_case exactly as our own onboarding wizard sends them, envelope field names camelCase.
• Request bodies are JSON (Content-Type: application/json).
• Language (revision 15, rewritten in revision 17: the mechanics, no language named). Every text of this API is served in English today: the questionnaire with its warning and acknowledgement sentences (11.1), the operator disclosure of section 8 (and the deprecated risk warning members beside it, still served), the declaration sentences of 9.2 and 11.4 (the MiFID sentences served by GET /texts, 11.7, since revision 18), every refusal sentence in msg. No other language is announced; availableLocales is the truth. The parameter exists so that a language can be added without a wire change. A text we serve in more than one language takes a locale query parameter (a language tag xx or xx-YY, resolved to xx; _ is accepted for -; the Accept-Language header is not read; today the questionnaire read, 11.1). The answer always states locale (what was served), requestedLocale, localeFallback and availableLocales. A language we do not serve answers the English text as a whole, never a mix. Served text is precomposed Unicode. A write never falls back: send the locale and the textHash of the read you rendered (11.2). Question and option ids are the same in every language. The rule of section 8 stands for every text you render as served, the operator disclosure, the key information documents, the declaration sentences and the questionnaire (never rephrase, translate or shorten them yourself): do not translate the served regulated texts yourself.

8. Partner-level reads

GET /partner/v1/me

The partner profile, reliance status, limits, the calling key, the webhook state, since revision 9 the FIX gateway's state (fix), since revision 10 the operator disclosure as we serve it (disclosures), beside the retail risk warning members that revision 16 deprecates (still served, see the display duty below), since revision 17 the questionnaire's schedule in one glance (appropriatenessTest, 11.1), since revision 21 the state of your app order commands (appOrders, section 22), and since revision 28 the perpetual demo as it applies to you (demo, section 23).

{
  "code": 0,
  "data": {
    "partner": {
      "partnerId": 7, "code": "NEOBROKER1", "name": "Neobroker One", "legalName": "Neobroker One GmbH", "country": "DE",
      "licenceType": "MICA_CASP", "relianceStatus": "APPROVED", "status": "ACTIVE", "sandbox": true,
      "custodyModel": "PARTNER", "collateralAsset": "USDe",
      "limits": {"readPerMinute": 600, "tradePerMinute": 120},
      "allowedCidrs": ["203.0.113.0/24"]
    },
    "key": {"keyId": 31, "label": "production backend", "prefix": "pbk_1f9c2d", "scope": "TRADE", "createdAt": 1788307200000, "lastUsedAt": 1788310800000},
    "webhook": {"url": "https://partner.example/hooks/barriers", "active": true},
    "fix": {"enabled": true, "port": 9850, "sessions": [{"keyPrefix": "pbk_1f9c2d", "connectedAt": 1788483600000, "lastInboundAt": 1788483660000}]},
    "disclosures": {
      "legalEntity": "PM MTF Ltd",
      "riskWarning": {
        "standard": "Perpetual contracts and barrier contracts are complex instruments and come with a high risk of losing money rapidly due to leverage. [the percentage sentence with our signed figure] You should consider whether you understand how these products work and whether you can afford to take the high risk of losing your money.",
        "abbreviated": "[the percentage sentence with our signed figure] You should consider whether you can afford to take the high risk of losing your money.",
        "reducedCharacter": "[the reduced-character percentage sentence with our signed figure]",
        "lossPercent": 67, "figureDate": "2026-07-01", "windowFrom": "2025-07-01", "windowTo": "2026-07-01", "fallback": false
      },
      "operatorDisclosure": {
        "signpost": "PM MTF Ltd provides this service as your broker and also operates the Kronos X MTF on which your orders are executed. Read our conflicts of interest summary.",
        "conflictsSummaryUrl": "https://barriers.com/legal/conflicts-summary"
      },
      "asOf": 1788310800000
    },
    "appropriatenessTest": {"version": 1, "effectiveAt": 1786865712000, "availableLocales": ["en"], "next": null},
    "appOrders": {"enabled": true, "issuer": "https://id.neobroker.example", "audience": "https://dev.brokerage.perpetuals.com/app", "jwksUrl": "https://id.neobroker.example/.well-known/app-order-keys.json", "kids": ["2026-10-a"], "lastFetchAt": 1788310500000, "lastError": null},
    "demo": {"perp": {"enabled": true, "available": true, "virtual": true, "currency": "USD", "startingBalance": "10000.000000", "topUpMaxPerCall": "10000.000000",
             "topUpMaxTotal": "90000.000000", "retentionDays": 30, "maxOpenOrders": 50, "limits": {"readPerMinute": 600, "tradePerMinute": 120}}},
    "asOf": 1788310800000
  }
}

appOrders (revision 21, additive, read only; section 22): enabled is true when our operations switched your app order commands ON AND the host you reached serves them (an audience is configured there); issuer is the exact iss your tokens must carry, audience the exact aud (null while the host serves no app order command), jwksUrl the https URL we fetch your public keys from, kids the key ids of our last good fetch of that set, lastFetchAt its time (Unix ms, null before the first good fetch) and lastError the error of our last failed fetch (null when the last fetch succeeded). The settings are agreed with us and set by our operations under four eyes; nothing here is written through this API. Read it after you publish a new key (22.4): the new kid appears here once we fetched it.

demo (revision 28, additive, read only; section 23): perp.enabled is your partner switch of the perpetual demo (OFF by default, set by our operations), perp.available is true when that switch is ON AND our global demo switch is on AND the host you reached runs the demo; virtual is always true and currency always USD; startingBalance, topUpMaxPerCall and topUpMaxTotal are the account's figures in virtual USD (23.3), retentionDays the retention of 23.3, maxOpenOrders the live order cap of an account, limits the demo's own rate windows (23.8).

appropriatenessTest (revision 17, additive): the questionnaire version in force at asOf with its effectiveAt and availableLocales, and next, the announced version's {version, effectiveAt, previousAcceptedUntil, changeClass, renderingChanged} while one is announced, else null; the whole schedule is on GET /appropriateness-test (11.1).

licenceType is one of MICA_CASP, MIFID_IF, EMI, CREDIT_INSTITUTION, OTHER. webhook is null until one is registered. custodyModel is BROKER or PARTNER (section 13) and collateralAsset the display name of the partner's stablecoin under PARTNER custody (empty otherwise). fix (section 20): enabled says whether the router you reached serves the FIX gateway, port is its TCP port (null when disabled; the hostname is the Partner API hostname of section 20, told at onboarding), sessions lists your live FIX sessions with the prefix of the key each logged on with and the two times, nothing else. Since revision 11 enabled means our acceptor is LISTENING on that host: it reads false, with port null, while the acceptor is not listening (a start failure our operations are retrying), so a refused connection beside enabled: false is ours to fix (a value rule, no field moved).

disclosures (revision 10; optional and additive, null on a host without the service) is the SAME document our own clients read on our public route, so what you render of it is exactly what we serve. In the example above the three deprecated sentences are abridged: [...] stands for the percentage sentence carrying our signed figure.

THE DISPLAY DUTY (revision 16, 2026-09-22). By the operator's decision of 2026-09-22 the CFD-related standard retail risk warning is NOT REQUIRED for barrier contracts, and this reference no longer requires you to display it for barrier contracts or for any other product we offer through this API. The eight riskWarning members of disclosures on GET /me (standard, abbreviated, reducedCharacter, lossPercent, figureDate, windowFrom, windowTo, fallback) are DEPRECATED under section 21: still served for compatibility with their shape and meaning unchanged, removed on /partner/v2; you MAY stop rendering them at once, nothing on our side reads whether you do, and a client that still renders them renders them as served. The same members of the document our own clients read on our public route stay served unchanged (a change there is a revision of that route's own changelog, never of this reference). Our own portal stopped rendering the three forms on the same decision, and our app does from its next build; our compliance function still computes and signs the quarterly figure, which is still served in the deprecated members. What STANDS: show operatorDisclosure.signpost with the conflicts summary link on the account screen; re-read GET /me at least daily so a changed signpost or link reaches your clients within a day; put nothing of it on a push notification. The texts you must still render as served, the operator disclosure of this section, the key information documents (12.2), the declaration sentences (9.2, 11.4) and the questionnaire (11.1), change only with our compliance function's sign-off or a re-characterisation of the products; never rephrase, translate or shorten them yourself. Whether a barrier-specific risk sentence set (the guaranteed stop at the barrier and the leverage definition our own surfaces show) will be served here and required of you is an open question of ours; until it is decided nothing of it is served and nothing of it is required. Whether item (4) of the categorisation warning CAT-WARN-2026-09 v1 (11.6.1), which names the standardised risk warning and the loss-percentage disclosure among the protections a retail client receives, is re-versioned after this decision is a second open question of ours, for our compliance function; the version in force stands as served and you show it verbatim until a new version is published and announced (11.6.1).

GET /partner/v1/clients?limit&before&q&state&level

The partner's clients, newest first. limit 1 to 200 (default 50), before a client id, q a case-insensitive text filter over e-mail, display name and partnerClientRef, state a lifecycle state, level one of NONE, MICA, MICA_MIFID.

{
  "code": 0,
  "data": {
    "clients": [
      {
        "clientId": 412, "clientUid": "BARR-00000412", "partnerClientRef": "cust-001",
        "email": "jan.kowalski@example.com", "displayName": "Jan Kowalski", "clientType": "NATURAL",
        "verificationLevel": "MICA", "lifecycleState": "ACTIVE", "categorization": "RETAIL", "riskState": "NORMAL",
        "cashUsdc": "1500.000000", "createdAt": 1788307300000, "legalEntity": null,
        "pendingCategorizationRequest": {"requestId": 77, "target": "PROFESSIONAL", "basis": "ELECTIVE", "status": "PENDING"}
      }
    ],
    "hasMore": false,
    "nextBefore": null
  }
}

riskState is the margin engine's state for the account (null when the engine is not attached). cashUsdc is the spendable USDC cash. clientType (revision 8) is NATURAL or LEGAL; a legal entity (section 9.7) carries legalEntity {legalName, lei, leiStatus, registrationNumber, registrationCountry, entityStatus} (the file's LEI status FORMAT_OK, ISSUED, LAPSED, ...; entityStatus SUBMITTED, APPROVED or REJECTED), a natural person null. pendingCategorizationRequest (revision 8, section 11.6) is the client's categorisation request that is PENDING or APPROVED and not yet applied (the cooling period), as {requestId, target, basis, status}, else null; categorization is the categorisation in force (RETAIL or PROFESSIONAL).

GET /partner/v1/clients/{clientId} and GET /partner/v1/clients/by-ref/{partnerClientRef}

One client row in the shape above; 404 code 4004 for an unknown or foreign client.

GET /partner/v1/summary

{
  "code": 0,
  "data": {
    "asOf": 1788310800000,
    "clients": {"total": 128, "byState": {"ACTIVE": 121, "KYC_PENDING": 5, "RESTRICTED": 2}, "byLevel": {"MICA": 80, "MICA_MIFID": 43, "NONE": 5}, "byType": {"NATURAL": 120, "LEGAL": 8}},
    "clientCash": [{"currency": "USDC", "cash": "184210.500000", "reserved": "2500.000000", "total": "186710.500000"}],
    "openBarriers": 14, "openSwaps": 3, "pendingDeposits": 2, "pendingWithdrawals": 1, "pendingReviews": 1, "pendingCategorizationRequests": 1
  }
}

pendingReviews counts KYC packages in SPOT_CHECK or DOCUMENTS_REQUESTED; pendingCategorizationRequests (revision 8) the categorisation requests of your clients that are PENDING or APPROVED and not yet applied (section 11.6).

9. Onboarding under reliance

9.1 POST /partner/v1/clients

Scope TRADE, reliance APPROVED, Idempotency-Key recommended. Creates the client, records the six MiCA blocks as approved under the partner's attestation, records the partner's identity check as a verified identity session, stores the KYC package (revision 1), runs OUR screening and grants verification level MICA through exactly the same decision function our compliance officers use. Answer 201.

Body (envelope fields camelCase, block payloads snake_case):

Blocked jurisdictions (registration and residential address), the default list: US, KP, IR, MM, SY, CU, RU, UA.

Validation failures answer 400 code 4000 with data.errors, a map of dotted field paths to one sentence each, for example "kyc.personalInfo.address.country": "We are unable to accept applications from this jurisdiction at this time.", "kyc.taxResidency.tax_residencies.0.tin": "Invalid TIN format for the selected country.", "identityCheck.verifiedAt": "The identity check must be no older than 12 months.". List items are addressed by their index (citizenships.1, associations.0.dob). Nothing is created when any field fails.

9.2 The kyc sections (the six MiCA blocks)

The block payloads are validated by the same rules as our own onboarding wizard. Every string is trimmed; enumerations are exact lower-case tokens. Two document references are optional under reliance (utility_bill_document_id, w9_document_id), as is the identification block's document_ids list. On POST /clients they must be OMITTED: no document can be on file before the client exists, so a reference there answers 400 code 4000 with the field sentence "Omit document references on POST /partner/v1/clients: a document is uploaded to the client AFTER it exists (POST /partner/v1/clients/{clientId}/documents) and referenced in a later PUT /partner/v1/clients/{clientId}/kyc." and nothing is created (revision 6; the upload route needs the client, so no id can exist before it). On PUT .../kyc (section 10.1) a reference must name a document uploaded for this client through section 10.3; an unknown id answers "This document was not found among your uploads.".

personalInfo (block PERSONAL_INFO)

identification (block IDENTIFICATION)

taxResidency (block TAX_RESIDENCY)

tax_residencies: array of at least one object, no country twice:

fatca (block FATCA)

pep (block PEP)

A public function object: position (one of head_of_state, head_of_government, minister, deputy_or_assistant_minister, member_of_parliament, party_governing_body_member, high_judicial_body_member, auditors_or_central_bank_board, ambassador_or_charge_daffaires, high_ranking_armed_forces_officer, state_owned_enterprise_body_member, international_organisation_director, mayor), country (ISO alpha-2), institution (at most 100), start_date (YYYY-MM-DD, 1900 or later, not in the future), end_date (optional, not before the start).

An association: full_name (at most 100), dob (YYYY-MM-DD, at least 18), nationality (ISO alpha-2), address (at most 200), the public function fields above, and relationship (one of spouse, child, son_daughter_in_law, parent, joint_beneficial_ownership, other_close_business_relations, sole_beneficial_ownership).

declarationsMica (block DECLARATIONS_MICA)

Fifteen booleans, every one true: fatca_crs_accurate, fatca_crs_responsible, fatca_crs_notify_changes, fatca_crs_disclosure, fatca_crs_consequences, accept_legal_docs, accuracy_of_info, market_conduct, aml_compliance, recording_consent, data_protection, notify_changes, cooperate_authorities, authorised_client, crypto_asset_risk_acknowledged. Add acceptedAt (Unix ms, when the client made the declarations in your interface); it is stored with the package as received.

The fifteenth key (revision 10, the crypto-asset risk acknowledgement: the client acknowledges that crypto-assets are volatile and unprotected and that the spot books are traded prefunded without leverage) is REQUIRED from the published cut-over date, 00:00 UTC. Until then a declarationsMica block WITHOUT the key (absent) is accepted on POST /clients and on PUT /clients/{clientId}/kyc and stored as received; a PRESENT value other than true is refused at any time with the field's own sentence (kyc.declarationsMica.crypto_asset_risk_acknowledged: "This declaration must be acknowledged."). After the cut-over an absent key is refused the same way. Ship the key with your next release: it is accepted today.

The sentences the fifteen keys stand for (revision 15). Each key is the client's acknowledgement of one declaration sentence our own onboarding shows. The wording of that set is TO BE CONFIRMED by our compliance function before it is printed here: it is not final, this revision prints none of the fifteen sentences, and no text id is assigned to them yet (the MiFID set of 11.4 is printed where confirmed). Until the confirmed set is printed, the declarations your interface shows for these keys are your own wording under your attestation, as today; a later revision prints the confirmed sentences with a text id each and, once served, a language convention (section 7).

9.3 identityCheck

The record is stored as a verified identity session of provider partner and mirrored into the client's IDENTITY_CHECK block as APPROVED.

The age of verifiedAt (no older than 12 months, 366 days) is checked at SUBMISSION only: on POST /clients, on a PUT .../kyc that carries an identityCheck (10.1) and per person of a legal entity's file (9.7). Nothing reads the value again afterwards: the IDENTITY_CHECK block stays APPROVED and no re-verification cadence follows from the 12 months. An identityCheck you choose to send with a later revision records a further verified session and must itself be no older than 366 days at that moment. documentExpiry is validated and kept with the record, but it is NOT the date we track after onboarding: that is kyc.identification.expiration_date (10.6).

9.4 attestation

9.5 Worked example

Request:

POST /partner/v1/clients HTTP/1.1
Host: dev.brokerage.perpetuals.com
Authorization: Bearer pbk_1f9c2d0b3e7a4c5d6e7f8091a2b3c4d5e6f7a8b9
Idempotency-Key: 5b1c0f6e-2a7d-4d0e-9d3e-7a2f1c9b8e10
Content-Type: application/json

{
  "partnerClientRef": "cust-001",
  "email": "jan.kowalski@example.com",
  "clientType": "NATURAL",
  "categorization": "RETAIL",
  "kyc": {
    "personalInfo": {
      "first_name": "Jan", "last_name": "Kowalski", "date_of_birth": "1980-05-14",
      "country_of_birth": "PL", "citizenships": ["PL"],
      "phone_country_code": "+48", "phone_number": "600123456",
      "address": {"country": "DE", "street_name": "Hauptstrasse", "number": "1", "city": "Berlin", "postal_code": "10115"}
    },
    "identification": {"type": "passport", "country_of_issuance": "PL", "number": "AB123456", "expiration_date": "2031-01-01"},
    "taxResidency": {"tax_residencies": [{"country": "DE", "has_tin": true, "tin": "12345678901"}]},
    "fatca": {"us_person_status": false},
    "pep": {"is_pep": false, "has_associations": false},
    "declarationsMica": {
      "fatca_crs_accurate": true, "fatca_crs_responsible": true, "fatca_crs_notify_changes": true, "fatca_crs_disclosure": true,
      "fatca_crs_consequences": true, "accept_legal_docs": true, "accuracy_of_info": true, "market_conduct": true,
      "aml_compliance": true, "recording_consent": true, "data_protection": true, "notify_changes": true,
      "cooperate_authorities": true, "authorised_client": true, "crypto_asset_risk_acknowledged": true, "acceptedAt": 1788307200000
    }
  },
  "identityCheck": {
    "provider": "ondato", "reference": "idv-7f3a9c", "method": "video", "verifiedAt": 1788220800000,
    "documentType": "passport", "documentCountry": "PL", "documentExpiry": "2031-01-01"
  },
  "attestation": {
    "cddPerformedAt": 1788220800000, "cddStandard": "MICA_CASP_CDD",
    "screening": {"sanctionsClear": true, "pepChecked": true, "adverseMediaChecked": true, "screenedAt": 1788220900000, "provider": "sumsub"},
    "riskRating": "LOW", "attestedBy": "compliance@neobroker.example", "documentsAvailableOnRequest": true
  }
}

Response 201 Created:

{
  "code": 0,
  "data": {
    "clientId": 412,
    "clientUid": "BARR-00000412",
    "partnerClientRef": "cust-001",
    "verificationLevel": "MICA",
    "lifecycleState": "ACTIVE",
    "status": "ACTIVE",
    "kycPackageId": 58,
    "requirements": {
      "TRADE:PERP": ["ACCOUNT_PURPOSE", "EMPLOYMENT_FINANCIAL", "SOURCE_OF_WEALTH", "APPROPRIATENESS", "DECLARATIONS_MIFID"],
      "TRADE:SPOT": [],
      "TRADE:BARRIER": ["ACCOUNT_PURPOSE", "EMPLOYMENT_FINANCIAL", "SOURCE_OF_WEALTH", "APPROPRIATENESS", "DECLARATIONS_MIFID"],
      "TRADE:STAKING": ["ACCOUNT_PURPOSE", "EMPLOYMENT_FINANCIAL", "SOURCE_OF_WEALTH", "APPROPRIATENESS", "DECLARATIONS_MIFID"],
      "DEPOSIT:CRYPTO": [],
      "WITHDRAW:CRYPTO": [],
      "DEPOSIT:FIAT": ["BANK_ACCOUNT"],
      "WITHDRAW:FIAT": ["BANK_ACCOUNT"]
    },
    "review": null
  }
}

requirements maps every gated action to the blocks the client still lacks; an empty list means the action is open. At MICA the client may already deposit, withdraw and trade crypto spot; the MiFID families wait for section 11. (DEPOSIT:FIAT and WITHDRAW:FIAT are the portal's fiat rails; partner money moves through sections 14 and 15 and never asks for a bank block.)

9.6 What happens on our side

1. Gate: partner ACTIVE and reliance APPROVED (else 4037 / 4036), scope TRADE.
2. Validation of every section as above; any error answers 400 with the map and creates nothing.
3. The client row is created (NATURAL, RETAIL, the display name from the personal block, the residency, onboardingSource PARTNER_RELIANCE, your reference).
4. The six MiCA blocks are written as SUBMITTED then APPROVED with the data as received, decidedBy partner:<CODE> on our records (the verification view of section 11.5 shows the label PARTNER); the identity session is recorded and the IDENTITY_CHECK block approved.
5. The package (revision 1, status ACCEPTED) is stored.
6. OUR sanctions and PEP screening runs synchronously. The MiCA grant then runs the same checks as a compliance approval (the screening gate first). On success: level MICA, lifecycle ACTIVE, a decision row with actor partner:<CODE> and reason "reliance onboarding", the webhook client.onboarded.
7. On a screening HIT or POSSIBLE match awaiting a disposition (or any other refusal of the grant): the client stays KYC_PENDING at level NONE, the package becomes SPOT_CHECK, a compliance case is opened and the answer is still 201 with status: "PENDING_REVIEW" and review: {reason, caseId}; the webhook client.review_required fires (client.onboarded does not: it marks the grant). Our compliance officers disposition the hit and decide the level; the client's level then changes on our side and you learn of it through client.verification_decision and GET .../verification. Since revision 10 (2026-09-10) a politically exposed person takes the same path: a client whose pep section declares is_pep or has_associations, or who carries a PEP true match on our screening (for a legal entity, a PEP among its persons too), also lands PENDING_REVIEW until our senior management approves the MiCA level under our maker-checker (review.reason names MICA_PEP_APPROVAL); the event and the fields are the ones above, no new value is introduced.

{
  "code": 0,
  "data": {
    "clientId": 413, "clientUid": "BARR-00000413", "partnerClientRef": "cust-002",
    "verificationLevel": "NONE", "lifecycleState": "KYC_PENDING", "status": "PENDING_REVIEW", "kycPackageId": 59,
    "requirements": {"TRADE:PERP": ["PERSONAL_INFO", "..."], "DEPOSIT:CRYPTO": ["..."]},
    "review": {"reason": "screening HIT: 1 hit(s) await a disposition", "caseId": 3021}
  }
}

9.7 Legal entities

Revision 8 (the addendum of 2026-09-06, section 3). A legal entity is onboarded under reliance with clientType: "LEGAL". The body carries TWO things: the natural-person kyc sections and identityCheck of the REPRESENTATIVE WHO OPERATES THE ACCOUNT (the account holder: the person must be identified and verified like any client, the rules of 9.2 to 9.4 unchanged), plus the kyb object with the entity file: the entity itself (the LEI is required), the CRS and FATCA classification of the entity, the persons (beneficial owners, intermediate holdings, directors and authorised representatives) and the documents you hold. We write the entity file exactly as our onboarding team would, check the LEI, screen the account holder, the entity itself and every person against OUR lists, and grant level MICA through the same decision function as for a natural person: status: "ACTIVE" when every screening is clean, PENDING_REVIEW (a case for our compliance officers) otherwise. The client's display name is the legal name; the entity contracts with PM MTF Ltd, the e-mail is the entity's contact address (partner clients have no login). The natural-person body and answer are unchanged.

Top-level fields for LEGAL (beside partnerClientRef, email, categorization and residencyCountry of 9.1):

kyb.entity (the file's own vocabulary, camelCase):

kyb.entityClassification (the CRS and FATCA facts of the entity; the FATCA block of 9.2 describes the account holder, not the entity):

The classification is kept as received (the package) and recorded on the file (an ENTITY_CLASSIFICATION_SET event); it never blocks the grant.

kyb.persons[] (1 to 50 entries; each role one of UBO, SHAREHOLDER_ENTITY, DIRECTOR, REPRESENTATIVE; SENIOR_MANAGING_OFFICIAL is accepted as an alias and recorded as a UBO with controlType SENIOR_MANAGING_OFFICIAL):

• Every natural person: firstName, lastName (100 each), birthDate (YYYY-MM-DD, at least 18), nationality (ISO), isPep (boolean; pepDetail required when true), optional email (the person's, never a login), phone (40).
• UBO: ownershipPct (0 to 100), controlType (OWNERSHIP default, VOTING_RIGHTS, OTHER_CONTROL, SENIOR_MANAGING_OFFICIAL), optional parentIndex (the zero-based index of an EARLIER SHAREHOLDER_ENTITY entry the stake is held through: "parentIndex must name an earlier SHAREHOLDER_ENTITY entry."), and the identity facts below.
• SHAREHOLDER_ENTITY (an intermediate holding in the chain): entityName (200), ownershipPct (0 to 100), optional entityLei (check digits), entityRegistration, parentIndex. An identityCheck on a holding is refused: "An intermediate holding has no identity check."
• DIRECTOR: position (120), appointedOn (YYYY-MM-DD); identityCheck optional (a director is identified and name-screened, verified when you have the record).
• REPRESENTATIVE: powers (SOLE, JOINT, LIMITED; powerLimits required with LIMITED), powerSource (ARTICLES, BOARD_RESOLUTION, POWER_OF_ATTORNEY, REGISTER), optional position, appointedOn, and the identity facts below.
• The identity facts of a UBO and a REPRESENTATIVE (the persons the law requires to be identified AND verified): countryOfResidence (ISO), idType (passport, national_id, drivers_license, residence_permit), idNumber (80), idCountry (ISO), idExpiry (after today), address (the shape of registeredAddress) and identityCheck (the shape of 9.3: "The identity check record is required for a beneficial owner and for a representative.").
• Exactly one entry has accountHolder: true; it must be a REPRESENTATIVE ("Exactly one REPRESENTATIVE must be marked accountHolder.") whose firstName, lastName and birthDate equal kyc.personalInfo.first_name, last_name and date_of_birth ("The account holder must be the person of kyc.personalInfo."). Its identity check is the top-level identityCheck.
• The file must be coherent as our onboarding team would check it, before anything is written: at least one beneficial owner who reaches the 25 percent threshold directly or through the chain of holdings (or the senior managing official), the ownership percentages within 100 at every level, at least one director, an authorised representative who is the account holder. The sentences of that check come back on kyb.persons (for example "Name at least one director.").

kyb.documents[] (1 to 50 entries, {kind, reference, title?, issuedOn?, expiresOn?, note?}): kind one of CERTIFICATE_OF_INCORPORATION, REGISTER_EXTRACT, ARTICLES_OF_ASSOCIATION, SHAREHOLDER_REGISTER, DIRECTOR_REGISTER, UBO_REGISTER_EXTRACT, BOARD_RESOLUTION, POWER_OF_ATTORNEY, FINANCIAL_STATEMENTS, LEI_CERTIFICATE, REGULATORY_LICENCE, OTHER. The package must hold the document set of the table below (revision 10); a missing group answers kyb.documents with the sentence "Missing documents: ..." naming every missing group, lower-cased (a group with two kinds joined by "or", the groups joined by commas: "Missing documents: ubo register extract or shareholder register." for a package carrying only the three old kinds; "Missing documents: board resolution." for a third-country package without it). The REGISTER EXTRACT must carry issuedOn and it must lie within the last 90 days at the submit ("The register extract must have been issued within the last 90 days (issued on 2025-10-01).", or "The register extract needs its issue date (YYYY-MM-DD, within the last 90 days)." without a date); the age is our parameter and may change. reference is your own reference of the document you hold under the documents-on-request undertaking (1 to 200, required on POST /clients); a documentId is refused on POST /clients (no upload can exist before the client) and honoured on PUT .../kyc (10.1) and through purpose: "entity" on the upload route (10.3), which replaces the held row by your upload. A revision's full list has to keep the set satisfied (a list that drops a required group is refused with the same sentence).

A file already submitted keeps the document set it was submitted under; the table binds packages received from revision 10 on.

kyb.contact (optional): email (defaults to the top-level e-mail), phone (40), personIndex (a REPRESENTATIVE entry). Recorded on the file, never a login.

attestation.entityCdd (required for LEGAL, refused on a NATURAL body with "entityCdd applies to LEGAL clients only."):

Worked example:

{
  "partnerClientRef": "corp-001",
  "email": "treasury@acme-trading.example",
  "clientType": "LEGAL",
  "kyc": {"personalInfo": {"first_name": "Jan", "last_name": "Kowalski", "date_of_birth": "1980-05-14", "...": "..."}, "identification": {"...": "..."}, "taxResidency": {"...": "..."}, "fatca": {"...": "..."}, "pep": {"...": "..."}, "declarationsMica": {"...": "..."}},
  "identityCheck": {"provider": "ondato", "reference": "idv-9a1", "method": "video", "verifiedAt": 1788220800000, "documentType": "passport", "documentCountry": "PL", "documentExpiry": "2031-01-01"},
  "kyb": {
    "entity": {
      "legalName": "Acme Trading GmbH", "tradingName": "Acme", "legalForm": "GmbH",
      "registrationNumber": "HRB 123456", "registrationCountry": "DE", "registrationAuthority": "Amtsgericht Berlin-Charlottenburg",
      "incorporationDate": "2015-03-02", "lei": "5299000J2N45DDNE4Y28",
      "registeredAddress": {"country": "DE", "street_name": "Hauptstrasse", "number": "1", "city": "Berlin", "postal_code": "10115", "state": null},
      "businessAddress": null, "businessActivity": "proprietary trading of crypto-assets and derivatives",
      "industry": "banking_financial", "website": "https://acme-trading.example", "taxId": "DE123456789", "taxCountry": "DE",
      "isRegulated": false, "regulator": null, "listedExchange": null, "ownershipNote": null
    },
    "entityClassification": {"crsEntityType": "ACTIVE_NFE", "fatcaStatus": "ACTIVE_NFFE", "giin": null, "usTin": null, "taxResidencies": [{"country": "DE", "has_tin": true, "tin": "DE123456789"}], "controllingPersonsDeclared": true},
    "persons": [
      {"role": "UBO", "firstName": "Anna", "lastName": "Muster", "birthDate": "1975-06-01", "nationality": "DE", "countryOfResidence": "DE",
       "idType": "passport", "idNumber": "C01X00T47", "idCountry": "DE", "idExpiry": "2030-05-01",
       "address": {"country": "DE", "street_name": "Ringstrasse", "number": "7", "city": "Berlin", "postal_code": "10117"},
       "ownershipPct": 60, "controlType": "OWNERSHIP", "parentIndex": null, "isPep": false, "email": "anna@example", "phone": "+49301234567", "accountHolder": false,
       "identityCheck": {"provider": "ondato", "reference": "idv-9a2", "method": "video", "verifiedAt": 1788220800000, "documentType": "passport", "documentCountry": "DE", "documentExpiry": "2030-05-01"}},
      {"role": "SHAREHOLDER_ENTITY", "entityName": "Muster Holding AG", "entityLei": null, "entityRegistration": "CHE-123.456.789", "ownershipPct": 40, "parentIndex": null},
      {"role": "UBO", "firstName": "Peter", "lastName": "Muster", "birthDate": "1970-01-15", "nationality": "CH", "countryOfResidence": "CH",
       "idType": "passport", "idNumber": "X1234567", "idCountry": "CH", "idExpiry": "2029-12-31", "address": {"...": "..."},
       "ownershipPct": 100, "controlType": "OWNERSHIP", "parentIndex": 1, "isPep": false, "accountHolder": false, "identityCheck": {"...": "..."}},
      {"role": "DIRECTOR", "firstName": "Anna", "lastName": "Muster", "birthDate": "1975-06-01", "nationality": "DE", "position": "Geschaeftsfuehrerin", "appointedOn": "2015-03-02", "isPep": false},
      {"role": "REPRESENTATIVE", "firstName": "Jan", "lastName": "Kowalski", "birthDate": "1980-05-14", "nationality": "PL", "countryOfResidence": "DE",
       "idType": "passport", "idNumber": "AB123456", "idCountry": "PL", "idExpiry": "2031-01-01", "address": {"...": "..."},
       "position": "Head of Treasury", "powers": "SOLE", "powerSource": "POWER_OF_ATTORNEY", "powerLimits": null, "appointedOn": "2024-01-10",
       "isPep": false, "email": "jan.kowalski@example.com", "phone": "+48600123456", "accountHolder": true}
    ],
    "documents": [
      {"kind": "CERTIFICATE_OF_INCORPORATION", "reference": "acme/coi/2015", "title": "Certificate of incorporation", "issuedOn": "2015-03-02"},
      {"kind": "REGISTER_EXTRACT", "reference": "acme/hrb/2026-08", "issuedOn": "2026-08-20"},
      {"kind": "ARTICLES_OF_ASSOCIATION", "reference": "acme/aoa/2022"},
      {"kind": "POWER_OF_ATTORNEY", "reference": "acme/poa/kowalski", "issuedOn": "2024-01-10"},
      {"kind": "UBO_REGISTER_EXTRACT", "reference": "acme/transparenzregister/2026-08"}
    ],
    "contact": {"email": "treasury@acme-trading.example", "phone": "+49301234500", "personIndex": 4}
  },
  "attestation": {
    "cddPerformedAt": 1788220800000, "cddStandard": "MICA_CASP_CDD",
    "screening": {"sanctionsClear": true, "pepChecked": true, "adverseMediaChecked": true, "screenedAt": 1788220900000, "provider": "sumsub"},
    "riskRating": "MEDIUM", "attestedBy": "compliance@neobroker.example", "documentsAvailableOnRequest": true,
    "entityCdd": {"uboIdentified": true, "uboVerified": true, "representativeAuthorityVerified": true, "registerCheckedAt": 1788220800000, "registerSource": "Handelsregister"}
  }
}

What happens on our side, in order: the validation of every part above (400 with the map, nothing created); in ONE transaction the client row (LEGAL, the legal name as the display name, the residency from the registered address), the account holder's six blocks and identity session as in 9.6, the entity file (the entity SUBMITTED with the LEI status FORMAT_OK, every person with the account holder linked to the account, every document as a row held by you, the four KYB blocks ENTITY_INFO, ENTITY_DOCUMENTS, UBO_DECLARATION, REPRESENTATIVES submitted, the file's events), the package (revision 1, payload {kyc, kyb}); after the commit the LEI check (the format always; the GLEIF registration status when we have the lookup configured, recorded on the file, never blocking this grant: a LAPSED or RETIRED status refuses the MiFID level later, 11.4), OUR screening of the account holder, of the entity itself (by legal name and LEI) and of every person, synchronously and, for the persons of a large file, several at a time within a fixed budget for the whole file (a person our provider has not answered for inside it counts as a screening that could not run), then the MiCA grant exactly as 9.6 step 6: ACTIVE at MICA with the four KYB blocks approved, our RTS 22 identifier record built with the LEI, the webhook client.onboarded; or PENDING_REVIEW as 9.6 step 7 (the case names the person or the entity whose screening awaits a disposition or could not run, an unavailable screening provider included; our compliance officers disposition the hit or re-run the screening and decide the level).

The 201 answer is the shape of 9.1 plus clientType and kyb:

{
  "code": 0,
  "data": {
    "clientId": 512, "clientUid": "BARR-00000512", "partnerClientRef": "corp-001", "clientType": "LEGAL",
    "verificationLevel": "MICA", "lifecycleState": "ACTIVE", "status": "ACTIVE", "kycPackageId": 61,
    "requirements": {"TRADE:PERP": ["ACCOUNT_PURPOSE", "..."], "TRADE:SPOT": [], "DEPOSIT:CRYPTO": []},
    "review": null,
    "kyb": {
      "entityStatus": "APPROVED", "lei": "5299000J2N45DDNE4Y28", "leiStatus": "FORMAT_OK", "leiCheckedAt": 1788307300000, "entityScreening": "CLEAR",
      "persons": [{"index": 0, "personId": 91, "role": "UBO", "accountHolder": false, "screening": "CLEAR"}, {"index": 1, "personId": 92, "role": "SHAREHOLDER_ENTITY", "accountHolder": false, "screening": "CLEAR"}, {"index": 4, "personId": 95, "role": "REPRESENTATIVE", "accountHolder": true, "screening": "CLEAR"}],
      "documents": [{"index": 0, "docId": 40, "kind": "CERTIFICATE_OF_INCORPORATION", "reference": "acme/coi/2015", "documentId": null}]
    }
  }
}

screening and entityScreening are CLEAR, PENDING_REVIEW (a hit awaits a disposition, or the provider could not run) or NOT_RUN (no screening provider installed); never a hit's content. index maps a row to its entry in your package (null on a later read for a row you did not list).

10. KYC maintenance and documents

10.1 PUT /partner/v1/clients/{clientId}/kyc

Scope TRADE, reliance APPROVED, Idempotency-Key recommended. Body: {kyc, attestation, identityCheck?} in the shapes of section 9. At least one MiCA section must be present in kyc; only the sections present are re-written (approved again under the partner); the attestation is required with every revision; identityCheck, when present, records a further verified identity session. A new package revision is stored.

When the personal block changes the client's identity (first, middle or last name, date of birth, or the set of citizenships), OUR screening runs again. A hit moves the client to RESTRICTED pending review, marks the package SPOT_CHECK, opens a compliance case and fires client.review_required.

{
  "code": 0,
  "data": {
    "clientId": 412, "clientUid": "BARR-00000412", "partnerClientRef": "cust-001",
    "kycPackageId": 61, "revision": 2, "status": "ACCEPTED",
    "verificationLevel": "MICA", "lifecycleState": "ACTIVE",
    "identityChanged": false, "screening": "NOT_RUN"
  }
}

screening is NOT_RUN (the identity did not change), CLEAR or PENDING_REVIEW. A closed account answers 409 code 4092.

When the personal block changes the client's name or date of birth (revision 3), the client's display name on our side follows the verified name and our RTS 22 client identifier record (the transaction-reporting identity built from the personal, identification and tax residency data) is rebuilt as a new revision; a revision that changes only the identification or tax residency data rebuilds that record too. Nothing of it changes the answer.

Re-onboarding after a rejection (revision 3). When our compliance rejected reliance for the client (kyc.rejected: level NONE, lifecycle KYC_PENDING, the latest package REJECTED), the same route is the re-onboarding: the body must carry ALL six MiCA sections in kyc, the identityCheck record (the rejected identity session was failed) and the attestation; a partial body answers 400 with the field map (identityCheck reads "The identity check record is required to re-onboard the client after a rejected package."). The call stores the next package revision, re-approves every block, records the new identity session, runs OUR screening again and re-runs the MiCA grant exactly like POST /clients (section 9.6 steps 4 to 7). MiFID blocks the client held were rejected with the package and stay under the compliance lock after the re-onboarding (revision 14, section 11): this call brings level MICA back, the MiFID level returns only after our compliance released those blocks. The answer adds the onboarding fields to the shape above:

{
  "code": 0,
  "data": {
    "clientId": 412, "clientUid": "BARR-00000412", "partnerClientRef": "cust-001",
    "kycPackageId": 74, "revision": 2, "status": "ACCEPTED",
    "verificationLevel": "MICA", "lifecycleState": "ACTIVE",
    "identityChanged": true, "screening": "CLEAR",
    "reonboarded": true, "grant": "ACTIVE", "review": null,
    "requirements": {"TRADE:PERP": ["ACCOUNT_PURPOSE", "..."], "DEPOSIT:CRYPTO": []}
  }
}

grant is ACTIVE (level MICA, the webhook client.onboarded fires again) or PENDING_REVIEW (a screening hit or another refusal: the client stays at level NONE, the package becomes SPOT_CHECK, a compliance case is opened, review: {reason, caseId}, the webhook client.review_required fires, screening reads PENDING_REVIEW). POST /partner/v1/clients with the same partnerClientRef answers 409 code 4092 pointing here (section 9.1) instead of creating a second account.

A legal entity (revision 8, section 9.7). The body of a LEGAL client is {kyc?, identityCheck?, kyb?, attestation}: at least one of the account holder's kyc sections or the kyb object must be present ("At least one of the kyc sections or the kyb object is required."); the attestation with entityCdd is required with every revision. Inside kyb every part is optional and REPLACES what it names: entity the whole entity (a new version; a new LEI resets its status to FORMAT_OK, is checked again and rebuilds our RTS 22 identifier record), entityClassification the classification, persons the FULL active list (an entry with personId updates that active person under the rules of 9.7, an entry without one is added, an active person absent from the list is removed from the file with the reason "removed in package revision N"; a new beneficial owner or representative needs its identityCheck; a new account holder needs the top-level identityCheck ("The top-level identityCheck is required when the account holder changes.") and the matching kyc.personalInfo; the previous holder's link is cleared), documents the full list (a reference already on file keeps its row, a documentId beside a reference upgrades the held row to your upload, a documentId alone adds your upload, an entry absent from the list is removed with the revision's reason; the three required kinds must remain: "A document needs a reference (held by you) or a documentId (your upload)."), contact the contact. A new or renamed person and a renamed or re-identified entity are re-screened synchronously: any hit takes the PENDING_REVIEW path above (the account RESTRICTED, the package SPOT_CHECK, the case, client.review_required), identityChanged reads true when anything screened again. The answer adds clientType and kyb as in 9.7. After a REJECT the re-onboarding of a legal entity needs the full body: every kyc section, the identityCheck, the whole kyb object ("The kyb object with the entity, the persons and the documents is required to re-onboard the legal entity after a rejected package.") and the attestation; the file is submitted again and the grant of 9.7 runs.

10.2 GET /partner/v1/clients/{clientId}/kyc

The latest package with its payload and attestation exactly as received:

{
  "code": 0,
  "data": {
    "kycPackageId": 61, "partnerId": 7, "clientId": 412, "clientUid": "BARR-00000412", "clientType": "NATURAL", "revision": 2,
    "status": "ACCEPTED", "receivedAt": 1788311000000,
    "payload": {"personalInfo": {"first_name": "Jan", "last_name": "Kowalski", "...": "..."}},
    "attestation": {"cddPerformedAt": 1788220800000, "cddStandard": "MICA_CASP_CDD", "...": "..."},
    "reviewedBy": null, "reviewedAt": null, "reviewNote": null
  }
}

Package statuses: ACCEPTED, SPOT_CHECK (under review by our compliance), DOCUMENTS_REQUESTED (we need the underlying documents; reviewNote says which), REJECTED (reliance refused for this client; reviewNote carries the reason; the client is set to KYC_PENDING at level NONE and must be re-onboarded with fresh data or documents through PUT .../kyc, section 10.1). reviewNote is answered only in the last two statuses. 404 code 4004 when the client has no package. reviewedBy is the reviewer's ROLE label (COMPLIANCE, ADMIN, SYSTEM for the automatic spot check, PARTNER), never a person's name (revision 6). A legal entity's payload (revision 8) is the pair {"kyc": {...}, "kyb": {...}} as received (the account holder's sections under kyc, the entity file under kyb, each key present only when the revision carried it); a natural person's payload stays the sections at the top level. clientType (NATURAL or LEGAL) says which of the two shapes the package carries.

A documents request (the status DOCUMENTS_REQUESTED, the webhook kyc.documents_requested with data {kycPackageId, revision, note}) is the decision of a compliance officer of ours in an individual case, under the documents-on-request undertaking of your attestation (9.4); nothing requests documents automatically. The officer's note names the documents wanted and is the only carrier of the request: read it as note on the webhook, or as reviewNote here and in the kycPackage summary of 11.5. Our officer can place the request on any package of the client that is not REJECTED, while these two reads show the LATEST package only: a request placed on an earlier revision is visible on the webhook alone, so keep the webhook's note with its kycPackageId. A request carries no deadline and gates nothing in our code: no route is refused because a package reads DOCUMENTS_REQUESTED, and no timer escalates it (a further measure would be a separate decision of our compliance and would reach you as its own event, 16.4). Answer it by uploading through 10.3 and, when the note asks for it, with a PUT .../kyc revision (10.1); our compliance then decides the package.

10.3 POST /partner/v1/clients/{clientId}/documents

Scope TRADE. Uploads one document for the documents-on-request undertaking: {name, contentType, dataBase64, purpose} with purpose one of identity, address, w9, other, entity. The content must be a JPEG, PNG or PDF (sniffed, contentType is informational), at most 8 MB, at most 20 live partner documents per client (409 code 4092 beyond). The stored document type follows the purpose: identity takes the identification block's type (passport, ...), address becomes utility_bill, w9 becomes w9_form, other stays other. Partner documents are never removable by the client. purpose: "entity" (revision 8, a LEGAL client only: "purpose entity applies to legal entities.") takes kind (a document kind of 9.7) and an optional reference: the upload is stored under the corporate document type of its kind and linked into the entity file, where it replaces the row you hold under that reference (else it is added as a new document of that kind); the answer adds kind, reference, kybDocId (the file's document id) and linked (true when a held row was replaced). kind and reference on another purpose answer 400 ("kind and reference apply to purpose entity only."). A request for the underlying document of a legal entity (kyc.documents_requested, the note names the kind) is answered this way without a further package revision.

{
  "code": 0,
  "data": {"documentId": 905, "type": "utility_bill", "purpose": "address", "filename": "bill.pdf", "mimeType": "application/pdf", "sizeBytes": 48213, "uploadedAt": 1788311100000, "source": "PARTNER"}
}

Errors: 400 code 4000 (purpose, empty or invalid base64, an unsupported format "The file must be a JPEG, PNG or PDF.", an empty file), 413 code 4000 ("The file is too large. The maximum size is 8 MB."). The whole request (the base64 text plus the JSON around it) must stay under the edge's 11.5 MiB body cap (section 4, code 4130), which a full 8 MB file does: 8 MiB of file is 11,184,812 bytes of base64.

Supporting evidence for the source of wealth. The SOURCE_OF_WEALTH block (11.4) is a declaration: three lists of tokens with their free texts, no amounts and no document reference. There is no upload purpose for source-of-wealth evidence and no block status that means "more information needed". Our compliance may ask for supporting evidence in an individual case, and what is built for that is the documents request of 10.2: the request arrives as kyc.documents_requested, the wanted documents are named in its note, and you upload each one here with purpose: "other" (stored as type other; JPEG, PNG or PDF, at most 8 MB, within the 20 live documents). Such an upload cannot be linked to a MiFID block: kind and reference apply to purpose: "entity" only, and the MiFID blocks belong to no package, so the request rides on the client's KYC package with the note alone naming what it is about. For a legal entity purpose: "entity" with a document kind of 9.7 remains the route for a corporate document. Reaching the enhanced due diligence threshold of 15.1 requests nothing by itself. This reference states no rule for when supporting evidence is required at that threshold: our compliance function decides that in the individual case, and a request reaches you as 10.2 describes.

10.4 GET /partner/v1/clients/{clientId}/documents

Metadata of every document on the client's file, ours and yours (never the content):

{"code": 0, "data": {"documents": [{"documentId": 905, "type": "utility_bill", "side": null, "filename": "bill.pdf", "mimeType": "application/pdf", "sizeBytes": 48213, "uploadedAt": 1788311100000, "deletedAt": null, "source": "PARTNER"}]}}

source is CLIENT, ONDATO (archived from our own identity provider), PARTNER, or EMPLOYEE (revision 10: a corporate document our staff added to a legal entity's company file from the CRM; it is listed to you and takes none of your 20 upload slots).

10.5 Consents (revision 10)

Every client of ours accepts our client-facing documents by version: the Terms and Conditions (TERMS), the privacy notice (PRIVACY), the order execution policy, the risk disclosure, the conflicts policy, the complaints procedure and the categorisation notice, each registered by our compliance function with a version tag, a title, a link and the archived text. A client you onboard accepts the versions in force at the onboarding IMPLICITLY: the acceptance instant is the moment our router writes the declaration blocks of POST /clients (the DECLARATIONS_MICA block stands for TERMS, PRIVACY, the conflicts policy, the risk disclosure and the complaints procedure; the DECLARATIONS_MIFID block of PUT .../mifid for the order execution policy, the risk disclosure, the categorisation notice and the conflicts policy). When we publish a NEWER version of a document the client's standing on it is older than the version in force (reconsentRequired) until an acceptance of the new version is recorded.

GET /partner/v1/clients/{clientId}/consents (READ) is the standing:

{"code": 0, "data": {"reconsentRequired": true, "gated": false, "documents": [
  {"doc": "TERMS", "title": "Terms and Conditions", "url": "https://barriers.com/legal/terms", "currentVersion": "2026-10", "effectiveAt": 1791158400000,
   "acceptedVersion": "2026-08", "acceptedAt": 1788311100000, "acceptedVia": "IMPLIED", "reconsentRequired": true, "gateFrom": 1793750400000},
  {"doc": "PRIVACY", "title": "Privacy Notice", "url": "https://barriers.com/legal/privacy", "currentVersion": "1.0", "effectiveAt": 1780000000000,
   "acceptedVersion": "1.0", "acceptedAt": 1788311100000, "acceptedVia": "IMPLIED", "reconsentRequired": false, "gateFrom": null}]}}

One entry per document that has a version in force; acceptedVia is PARTNER (recorded over this API), CRM (our operations), IMPLIED (the onboarding blocks) or PORTAL (our own portal, never for your client); gateFrom (Unix ms, null while the document is not gated or our switch is off) is the instant from which a pending re-consent on that document refuses new positions; gated says the gate would refuse a new position for the client right now.

POST /partner/v1/clients/{clientId}/consents (TRADE, Idempotency-Key) records the client's acceptance of the version in force on the client's behalf, after the client accepted the text in your app:

{"doc": "TERMS", "version": "2026-10", "acceptedAt": 1791200000000, "reference": "consent-8842"}

version must be the currentVersion of the read (409 code 4092 with data.currentVersion otherwise; 404 code 4004 when no version of the document is in force); acceptedAt (optional, Unix ms, in the past) is the instant the client accepted in your app and reference (optional, at most 200 printable ASCII characters) your record of it, both kept on our record's note; the record itself is stamped at our clock with channel PARTNER and actor partner:CODE, and the answer is the standing above (reconsentRequired and gated false for the document). A malformed body answers 400 code 4000 with data.errors (doc, version, acceptedAt, reference).

ANY REGISTERED DOCUMENT is acknowledged this way (BROKER-95): the policy documents above, ELECTRONIC_DELIVERY (the client's election to receive the documents electronically) and the KEY INFORMATION DOCUMENTS of the barrier markets, KID_<SYMBOL> for the normal contract and KID_<SYMBOL>_STRICT for the strict take profit contract (12.1 names the current version and the public PDF of each on GET /market-info, kid and kidStrict). A key information document rides the standing read like every registered document once a version of it is published: its row carries currentVersion and acceptedVersion, with scope HOLDERS a client who never acknowledged it reads reconsentRequired false and a holder of an earlier version reads true once a newer version is in force, and the row never gates (gateFrom null, gated untouched). The KID gate of 12.2 reads the record, not that flag: a RETAIL client's opening request needs the record for the CURRENT version, so compare the row's acceptedVersion with its currentVersion (the tag GET /market-info serves as kid.version and kidStrict.version) before the request. Your duty is to show the PDF from kid.url in your interface before the client's first request on the market and to record the acknowledgement here, which is the delivery evidence we keep (PRIIPs Article 14; the duty stays with PM MTF Ltd as the person selling under the reliance model of section 1). A RETAIL client's request without that record answers 403 code 4035 with data.error "KID_REQUIRED" (12.2); the same record with RISK_DISCLOSURE clears the strict take profit gate (RISK_DISCLOSURE_CONSENT_REQUIRED). The record is attributed on the client's and your audit streams.

THE GATE (the TERMS re-consent gate; a switch on our side, Consents:Gate, OFF on the development environment and off in production until our compliance function turns it on): while it is on, a client whose standing on TERMS is older than the version in force is refused every admission of NEW risk from that version's gateFrom (the later of its effective instant and fourteen days after its publication, plus a thirty day grace): POST .../orders for an opening order (a reduce-only order or one within the remaining reduce capacity of the opposite position passes), POST .../rfq, POST .../rfq/{rfqId}/accept on an OPENING request (the automatic accept skips its pass with the sentence as autoAcceptNote and the request stays open) and POST .../staking/{offerId}/accept, all with 403 code 4035 and data {doc, currentVersion, gateFrom}; POST .../rfq/preview answers the refused preview with the sentence. Never gated: reducing orders, the early close request and its accept, collateral reports, deposits and withdrawals. The sentence (msg) for a client of yours: "Our updated Terms and Conditions need your acceptance before you open new positions. You can still close positions, deposit and withdraw. Review them in your provider's app." (since 2026-09-12; it names your app because a client of yours holds no sign-in with us, section 1, while a direct client of ours reads a last clause naming our own portal). Show your own consent screen to the client and record the acceptance through the POST above; the refusal clears at once. Continued use never counts as an acceptance on our side.

THE NOTICE: when we publish a new version you receive the webhook client.consent_required (16.4) for every client of yours in scope, twice at most per version and client: stage ANNOUNCED at the publication of a version effective later, stage IN_FORCE when the version came into force (within a few minutes); a client who already accepted the version is not notified. A direct client of ours receives an e-mail at the same two instants; for a client you onboarded the CONSENT notices are the one notice the webhook substitutes: no consent mail from us, relay the webhook in your app. The notices our own regulatory duties require still reach your clients by e-mail at the contact address you gave us and never name you: the categorisation notice (11.6), the LEI notices and renewal reminders (11.4), the DORA Article 19(3) service incident notice (16.4, which you mirror in your app), the statement notices where enabled (they point at your app, the integration guide 3.9) and the address notice on a forgot-password or registration attempt (section 1 and the integration guide 3.9). Two more kinds of mail from our direct-client flow reach your clients today, because that flow has no partner variant: the identity document reminders and the expiry notice (10.6), and the verification decision notice our back office sends when a compliance officer of ours approves or refuses a verification level (a grant made through your own calls sends none, and neither does a rejected package). Prepare your support desk for them. All of these decision and document mails are written for a direct client of ours and speak of things your client cannot do with us (section 1): the two identity document mails ask the client to upload a valid document in our portal, the refusal notice asks the client to sign in to its account with us to see which sections need attention (and to open a support request from that account if it disagrees), and the approval notice speaks of the client's account with us (the notice of the MICA level also of depositing crypto). In those cases tell your client yourself, in your app, what to do (10.6 for the document, blocks[].reason of 11.5 for a refused section).

10.6 After onboarding: what we track, what we review, what never expires

Nothing you sent expires by time. No block of a client you onboarded is moved out of APPROVED by a clock, a sweep or a new questionnaire version: only a decision of our compliance does that (a verification decision or a rejected package, 16.4), and the block status EXPIRED cannot occur for a client of yours (11.5). The 12 months of identityCheck.verifiedAt are checked at submission only (9.3) and an appropriateness result has no validity period (section 11). Two things that run after onboarding are described here. Beside them our own sanctions and PEP screening of every client continues after onboarding (section 1), a legal entity's LEI is re-checked (11.4) and a professional categorisation is reviewed (11.6); a measure that follows from any of them is a decision of our compliance or a restriction and reaches you as its own event (16.4).

The identity document's expiry date. On an hourly pass we track the expiry date of the identity document of every client who holds a level, yours included. For a client you onboarded the tracked date is kyc.identification.expiration_date, the date of the IDENTIFICATION block you sent; identityCheck.documentExpiry is validated when you send it and kept with the identity check record, but it is NOT read by this pass, so keep expiration_date current.

• 60 days and 30 days before the date the client is sent a reminder by e-mail at the contact address you gave us (a date first seen inside the last 30 days gets one reminder).
• On the first pass after the date has passed (UTC calendar days: the day AFTER expiration_date, within about an hour) the client is sent an e-mail saying the document has expired, a CLOSE_ONLY restriction is engaged on the account on EVERY family, crypto spot included (a switch on our side, on by default), and an internal review of the account is opened for our compliance function.
• What the client loses: an opening order, a barrier request, the accept of an opening request and a swap take answer the close-only sentence of 11.4 as 400 code 4000 (the automatic accept skips its pass with the sentence as autoAcceptNote, and the preview answers accepted: false); reducing and closing always go through. Collateral reports, deposits and withdrawals are NOT blocked by this restriction.
• What does not change: the IDENTIFICATION and IDENTITY_CHECK blocks stay APPROVED, the level stays, the requirements map is unchanged and the client row keeps its lifecycleState (the pause is a restriction, not a lifecycle state, like the LEI pause of 11.4).
• You learn of the pause as margin.restriction_set and of its end as margin.restriction_lifted (16.4, data {kind, ref, ts}, at most one delivery each). Neither names the ground and no read of this API shows a client's restriction today (11.5), so compare your own copy of expiration_date to tell the client why. Do not rely on the delivery alone: the pass stamps the item with the time the pass started, so under the 30 second rule of 16.4 an item written late in a long pass is not forwarded. Read GET .../notifications for a client whose document date has passed, as for every feed event (16.4).
• The cure: send the renewed document's data through PUT .../kyc (10.1), the identification section with the new expiration_date plus the attestation; a date that is not after today is refused, as at onboarding. The PUT itself does not lift the pause: the next hourly pass records the new date and lifts the restriction it engaged, so allow up to an hour. A restriction our compliance set on its own stays.

The reminder and the expiry e-mail are the texts a direct client of ours receives: they ask the client to upload a valid identity document in our portal, which a client of yours cannot use (section 1). Tell your client yourself, ahead of the date, that the renewal goes through your app. A further measure our compliance officer takes inside that review in the individual case (a money restriction, a documents request) would reach you as its own event (16.4).

Our periodic review. We review every client who holds a level on a cycle set by OUR OWN risk rating of the client (not the riskRating you attest, and not the categorisation review of 11.6): every 12 months for a client we rate HIGH, every 24 for MEDIUM and every 36 for LOW, counted from the last completed review, else from the latest move of the client's level to MICA or MICA_MIFID (the MiCA grant, or the MiFID grant when it followed). The review is an internal task of our compliance function. Opening or completing one changes nothing on the wire by itself: no block, level, lifecycle state or restriction moves, no mail is sent and no webhook fires. It can lead to a documents request (kyc.documents_requested, 10.2), a restriction (margin.restriction_set) or a rejection (kyc.rejected), each the decision of an officer and delivered as 16.4 describes. We do not re-identify clients automatically by risk class, and this API has no route or event by which we ask you for a fresh identity verification: such a request would arrive as a documents request. Whether you push refreshed KYC data to us on your own refresh cycle (a PUT .../kyc when your own periodic review updates the client's data) is a matter for the reliance agreement between us; this API states and enforces no cadence.

11. MiFID appropriateness

The MiFID families (PERP, BARRIER, STAKING) need level MICA_MIFID: the four MiFID information blocks approved and an appropriateness result we hold as complete (PASS, or WARN acknowledged). The order of the two halves does not matter; the level moves the moment both are in place (for a result completed at the first or second attempt, below), and the webhook client.level_changed fires. A FAIL leaves the level at MICA; a retake is possible after the cooling period (24 hours from the attempt, Verification:AppropriatenessRetakeHours). Every attempt starts a cooling period whatever its outcome, so answers cannot be iterated.

An attempt is a SCORED submission (revision 15). An attempt is the call to POST .../appropriateness that answers 200: it carries attempt, it records the result, it fires appropriateness.result and it starts the cooling period. A refusal of that route (400, 404, every 409, 429) is not an attempt: it records no result, numbers no attempt and starts no cooling period, and nothing of it reaches you as an event. In particular the 409 of a stale version (11.2) costs the client nothing: re-read the questionnaire, re-render, and submit again under a new Idempotency-Key (section 5). The one refusal that leaves a record on our side is the compliance lock of this section, whose refused call is noted on our log by design; it numbers no attempt either. The answer stored under your Idempotency-Key is the one thing any refusal leaves behind (section 5).

An appropriateness result has NO EXPIRY. retakeAt is the earliest instant of a next attempt (the end of the cooling period), not a validity date. A new questionnaire version invalidates no recorded result: a result keeps the version it was taken against, and only answers rendered from a stale version are refused (11.2). Once the level is granted nothing re-reads the result, and the level is lost only by a decision of our compliance (16.4), never by time.

The automatic grant covers the first two attempts (revision 14). A result completed at attempt 1 or 2 (attempt on the result) grants the level through your calls. A result completed after MORE THAN TWO attempts is never granted automatically, the rule of our own onboarding: the moment both halves are in place the five MiFID blocks go SUBMITTED, the level stays MICA, and our compliance function decides. The call that completed the second half still answers 200, with granted false and grantRefusal "The appropriateness assessment was completed after more than 2 attempts: the MiFID level of this client is decided by our compliance function, and the MiFID blocks are under its review."; client.level_changed does not fire. While the blocks are SUBMITTED, PUT .../mifid answers 409 code 4092 ("The MiFID profile of this client is under review by our compliance function and cannot be changed until it is decided.", data {error: "MIFID_UNDER_REVIEW", lockedBlocks}) and a further assessment attempt answers the 409 of a section under review (11.2). The decision reaches you as client.verification_decision (16.4): an approval moves the level to MICA_MIFID; a refusal sets the blocks it names REJECTED, and the lock below applies.

The compliance lock (revision 14). A MiFID block our compliance function set REJECTED (the refusal of the MiFID level, 16.4, or a rejected package, 10.2; its decidedBy on 11.5 reads the role of our employee) is LOCKED: you cannot attest it again, and you cannot re-run the grant around it. While any of the five MiFID blocks is locked, PUT .../mifid, POST .../appropriateness and POST .../appropriateness/acknowledge answer 409 code 4092 with a sentence that names the blocks ("Our compliance function rejected EMPLOYMENT_FINANCIAL of this client. The MiFID blocks and the appropriateness assessment cannot be sent again until our compliance function releases the rejected blocks; contact our compliance function.") and data {error: "MIFID_BLOCKS_REJECTED", lockedBlocks: ["EMPLOYMENT_FINANCIAL"]}; nothing is written, no grant is attempted, and the refused call is recorded on our side. The lock is lifted by an officer of our compliance function and by nothing else: when our compliance invites a new submission it RELEASES the blocks, which then read DRAFT on 11.5 with decidedBy null and the client-facing sentence still in reason (what to correct); data blocks our compliance still held SUBMITTED are handed back as DRAFT with them. No event announces a release: it follows your exchange with our compliance function in the individual case, so re-read GET .../verification. After the release send PUT .../mifid again (under a NEW Idempotency-Key, section 5), and a new assessment when the APPROPRIATENESS block was the one rejected; the ordinary rules then apply (the grant, or the review of a result completed after more than two attempts). A REJECTED APPROPRIATENESS block whose decidedBy is null is the client's own FAILED attempt, never the lock: the retake after the cooling period stays open. Before revision 14 a repeat PUT .../mifid rewrote and approved a block our compliance had rejected and the grant ran again, which undid the refusal; that was a defect, corrected.

11.1 GET /partner/v1/appropriateness-test

The current questionnaire in client view (questions and options, never the points or thresholds), versioned. Render it in your interface as it is; the warning and acknowledgement sentences are part of the contract.

Versions are announced ahead (revision 17). Until revision 17 a new version was in force the moment our compliance function published it, with no advance notice, no event and no field on any read that announced one (revision 15 described that state). Until the code of this revision is deployed on an environment you use, we will not publish a new version on it without telling you directly beforehand: an operating commitment in force since 2026-09-22, when our compliance and operations people were instructed; a direct notice given under it is filed on our side against your partner record (section 21). The commitment ends on each environment with that deployment, because from then on the announced versions of this section replace it. Since revision 17 a version is PUBLISHED AHEAD of an effective instant: this read carries the schedule (status, publishedAt, effectiveAt, asOf, previous, next), the partner-level webhook appropriateness_test.version_changed (16.4) announces it at every stage, and GET /me shows the schedule in one glance (section 8). The questionnaire's own notice rule, as this read states it: a version that changes what you render (next.changeClass STRUCTURE or TEXT) is announced at least 14 calendar days ahead, in practice 30 (section 21); an URGENT publication (next.urgent true: a regulator's instruction, a defect in a question or in the scoring) may be shorter and may shorten or remove any acceptance of the previous version; at most one version is pending at a time; a SCORING_ONLY version changes nothing you render and needs no notice. previous and next.previousAcceptedUntil say whether and until when the previous version is accepted; they may be null, and we may end an acceptance early; a submission of the previous version is accepted strictly before acceptedUntil and refused at it (11.2 says what is scored and recorded then). Every published version has a higher number than the one before; numbers increase and need not be consecutive, so compare for equality and never hard code one. previous on this read is the truth about what is accepted now.

{
  "code": 0,
  "data": {
    "version": 1, "status": "IN_FORCE", "publishedAt": 1786865712000, "effectiveAt": 1786865712000, "asOf": 1790845260000,
    "previous": null,
    "next": {"version": 2, "publishedAt": 1790845200000, "effectiveAt": 1793577600000, "previousAcceptedUntil": 1793581200000,
             "changeClass": "STRUCTURE", "renderingChanged": true, "sentencesChanged": true, "changedQuestionIds": ["strictTakeProfitKnowledge"],
             "urgent": false, "rehearsal": false, "changeNote": "One knowledge question added and the warning sentence extended.",
             "textHash": "sha256:<the hash of the announced version's English text>", "availableLocales": ["en"], "missingLocales": []},
    "locale": "en", "requestedLocale": null, "localeFallback": false, "availableLocales": ["en"], "textRevision": 1,
    "textHash": "sha256:40e4befc4a2b55ba1eb2c2b33c302af867243e212fe6f38e151ca290a80cfc32", "languageElection": null,
    "questions": [
      {"id": "tradingExperience", "text": "Have you traded financial instruments (stocks, bonds, derivatives) before?", "section": null,
       "options": [{"id": "never", "text": "Never"}, {"id": "less_than_1_year", "text": "Less than 1 year"}, {"id": "1_to_3_years", "text": "1 to 3 years"}, {"id": "more_than_3_years", "text": "More than 3 years"}]},
      {"id": "riskUnderstanding", "text": "Do you understand that trading barrier products and perpetual contracts involves the risk of losing your entire investment?", "section": null,
       "options": [{"id": "yes", "text": "Yes, I understand"}, {"id": "no", "text": "No, I do not understand"}]}
    ],
    "sections": [{"id": "tradingExperience", "title": "Trading Experience", "questions": ["tradingExperience", "transactionCount", "averageTransactionSize"]}],
    "warningText": "Based on your responses, complex products such as barrier contracts and perpetual contracts may not be appropriate for you because your level of experience and knowledge does not seem adequate in order to understand the risks involved. These products carry a high risk of losing your entire investment.",
    "acknowledgeText": "I understand the risks and wish to proceed",
    "failText": null
  }
}

(The example shows two of the questions and an illustrative announcement; render every question the answer carries. The textHash of version 1 is the one every environment that serves the version 1 text answers.)

?version=. Without it the read serves the version in force. With ?version=N it serves the announced version AHEAD of its instant (render and test it before it applies), the version in force, or a former version (what an attempt recorded under it was rendered from). A value that is not a positive integer answers 400 code 4000 "version must be a positive integer."; a number we never published, a withdrawn one and an announced one that was overtaken answer 404 code 4004 "Unknown questionnaire version.".

?locale=. A language tag xx or xx-YY (_ accepted for -), resolved to its primary language (section 7): the version is served in that language when availableLocales lists it, else in English as a whole with localeFallback true and requestedLocale echoing what you sent, never a mix; a value that is no language tag answers 400 code 4000 with data.error LOCALE_MALFORMED. Question and option ids, the order and sections[].questions come from the version whatever the language; the words come from the served text. Our own clients' routes carry no language parameter.

THE RENDERING RULES. Render from this read at the time the user opens the assessment; never ship the questionnaire text with an app release. Cache the read at most 5 minutes per version and locale, treat next.effectiveAt as a hard expiry of the cache, and drop the cache on any appropriateness_test.* event (16.4) and on a stale 409 (11.2); an answer with localeFallback true is never cached beyond minutes (the language may arrive). Never switch on your own clock: switch when this read answers the new version with status IN_FORCE, or on the IN_FORCE stage of the event; flipping late is always safe (the previous version is accepted inside its acceptance, and a stale 409 costs nothing), flipping early never is (the announced version answers 409 before its instant). Always submit the version, locale and textHash of the read you rendered. Numbers increase and need not be consecutive: compare for equality, never hard code one. The acceptance of the previous version is frozen at the publication of its successor, except that we may end it early for a regulatory defect and that an urgent publication ends a running acceptance; a refusal that follows costs the client nothing (section 11); previous on this read is the truth. Rehearse the stale path on the development environment by posting version: 0, and the whole announcement path on request (section 18).

textHash names the words, version names the rules (revision 17). version (one integer across languages) names the structure, the scoring and the English master; any change to those, English wording included, is a new version. locale, textRevision and textHash name the exact words served: a corrected translation is a new textRevision under the SAME version, announced by appropriateness_test.text_changed (16.4). The hash is sha256: plus the lower-case hex of SHA-256 over the UTF-8 bytes (no byte order mark) of the CANONICAL TEXT of the served words: lines, each ended by LF (U+000A, the last included), each key=value, the value the string exactly as served with backslash, LF, CR and TAB escaped as \\, \n, \r and \t, no Unicode normalisation (served text is precomposed); in this order, family=APPROPRIATENESS_TEST, locale=<xx>, per question in the served order q.<questionId>=<text> then, only when the question carries a section label, q.<questionId>.section=<label>, then per option in order o.<questionId>.<optionId>=<text>; then, only when the version has sections, per section s.<sectionId>=<title> and s.<sectionId>.questions=<id>,<id>,... (comma joined, the version's list); then warningText=<text>, acknowledgeText=<text> and, only when present, failText=<text>. A line is emitted only for a member that is present, so a member added later never moves the hash of a text that does not have it, and the version number is not part of it: equal text has an equal textHash on every environment; compare the production hash with the one you tested. A worked example: one question q1 "Alpha?" with the options a "Yes" and b "No", no sections, the warning "Warn." and the acknowledgement "Ack.", served in English, has the canonical text

family=APPROPRIATENESS_TEST
locale=en
q.q1=Alpha?
o.q1.a=Yes
o.q1.b=No
warningText=Warn.
acknowledgeText=Ack.

and the textHash sha256:304e3a67e466077d15370f9369389dec92a466d3219d91115f9f9914183e92c4; recompute it with any SHA-256 tool over those seven lines, each ended by LF, to check your reading of the recipe.

The lines of a sentences family (revision 18). The same recipe serves the declaration sentences of 11.7: family=DECLARATIONS_MIFID, locale=<xx>, then per sentence in the order the read serves them t.<key>=<text> (a line only for a key present with a non empty text; the master version is no line). A worked example over two test sentences that are never served, a "Sample sentence, not a regulated text." and b "Second sample.", in English, has the canonical text

family=DECLARATIONS_MIFID
locale=en
t.a=Sample sentence, not a regulated text.
t.b=Second sample.

and the textHash sha256:c5bc2fc0cd220a241d7929a9110cb9512b8f3de4fdde4a9f9d69d26210e89b34; the three sentences of 11.4 as served at this publication hash to sha256:c04b33d65088c08d79bb62a3333d0741c098c541885e18f92e20ec50ecbaeafe (five lines, 1766 bytes), which GET /texts?family=DECLARATIONS_MIFID answers on every environment until our compliance function approves a later revision.

11.2 POST /partner/v1/clients/{clientId}/appropriateness

Scope TRADE. Body {version, locale, textHash, clientLanguage, languageElection, answers, representativePersonId}: version the version you rendered (11.1), locale and textHash the language and the text hash of the read you rendered (below), clientLanguage optionally the language your app showed the user (a language tag; recorded; a well formed value is never refused today, a value that is no language tag answers LOCALE_MALFORMED below), languageElection reserved (below), answers an object of question id to option id, every question answered (400 code 4000 names the first missing or unknown answer), representativePersonId for a legal entity (below). The result is recorded, the webhook appropriateness.result fires, and the MiFID grant is attempted at once.

version: REQUIRED as a JSON integer from the cut over (revision 17). The version check comes FIRST among the checks of the submission itself: before the cooling period, the section lock, the text checks and the answers are looked at; only the representative check of a legal entity and the compliance lock of this section's introduction come before it, and from the version check on a refusal writes nothing apart from the answer stored under your Idempotency-Key. Announced in revision 15 under section 21 and in force with the code of this revision: on the production environment from its first day, on the development environment from 2026-11-01 00:00 UTC, a body where version is absent or not a JSON integer (a string such as "1", a fraction, null) answers 400 code 4000 "version (the questionnaire version you rendered, a JSON integer) is required."; before that instant such a body is scored against the version in force, as revision 15 said. What the number you send decides:

data.currentVersion is on BOTH version refusals, so a client that knows neither label still re-reads. acceptedVersions lists the version in force and, while one is accepted, the previous version. renderingChanged false on the stale 409 means the number you sent names a version whose served English text equals the version in force's (a scoring-only change ended its acceptance): re-post the same answers under currentVersion without re-rendering; true (a text or structure change, or an unknown number) means re-read, re-render and keep the answers whose question and option ids survive.

locale and textHash: the words your user read (revision 17). Send the locale and the textHash of the read you rendered. Both are REQUIRED for every questionnaire version that is or ever was served in more than one language, and whenever the locale you send is not en. Send both always. Nothing on this route ever falls back to English silently. The checks, in this order, each before anything is written and each recording nothing:

Of a replaced text: a replaced text may stay acceptable until the instant the appropriateness_test.text_changed event states in previousAcceptedUntil (16.4); never rely on it. languageElection on this route is reserved, null today; do not build on it; a later revision defines it (LANGUAGE_ELECTION_UNKNOWN answers a value that names no sentence we served, section 4).

What a refusal of this route consumes: nothing (revision 15, widened in revision 17). The attempts rule of the introduction of this section, stated for this route: the 409s of a stale, announced or withdrawn rendering, the 400 of a missing version, locale or textHash or of an unanswerable body, the 429 of the cooling period and the 409 of a section under review, approved or under the compliance lock record no result, number no attempt, start no cooling period, fire no appropriateness.result and move neither retakeAt nor attempt; the next scored submission is numbered as if the refusal had not happened. After any of them the next submission carries a NEW Idempotency-Key (section 5; the "still in progress" answer about the key itself and the APPROPRIATENESS_VERSION_NOT_IN_FORCE refusal, whose key is given back, excepted).

{"version": 1, "locale": "en", "textHash": "sha256:40e4befc4a2b55ba1eb2c2b33c302af867243e212fe6f38e151ca290a80cfc32", "answers": {"tradingExperience": "more_than_3_years", "transactionCount": "more_than_50", "averageTransactionSize": "more_than_50000", "barrierProductKnowledge": "expires_worthless", "knockoutKnowledge": "closed_at_loss", "riskUnderstanding": "yes", "investmentObjectives": "speculation", "highRiskAllocation": "10_to_25"}}

{
  "code": 0,
  "data": {"version": 1, "outcome": "PASS", "score": 24, "requiresAcknowledgement": false, "retakeAt": 1788397200000, "attempt": 1,
           "submittedVersion": null, "supersededBy": null, "locale": "en", "textRevision": 1, "textHash": "sha256:40e4befc4a2b55ba1eb2c2b33c302af867243e212fe6f38e151ca290a80cfc32", "textAttested": true,
           "warning": null, "failure": null, "verificationLevel": "MICA_MIFID", "granted": true, "grantRefusal": null}
}

The 200 (revision 17): submittedVersion (the number you sent inside a scoring-only acceptance, else null), supersededBy (the version in force when the answers were scored under the previous version inside a grace, else null), locale, textRevision, textHash and textAttested (the words recorded for this attempt and whether you attested them with the hash), warning ({text, acknowledgeText, version} on a WARN: the sentences of the version your user SAW, in the recorded language; show them and acknowledge with 11.3; null otherwise) and failure (reserved, null today; do not build on it; a later revision defines it).

granted is true when this call moved the level to MICA_MIFID (the four blocks were already in place). grantRefusal (revision 8) is the sentence of a grant that was attempted and refused (a legal entity whose LEI is not in good standing, 11.4) or withheld for our compliance (revision 14: a result completed after more than two attempts, the introduction of this section), null when granted or when nothing was attempted yet. Outcomes: PASS, WARN (requiresAcknowledgement true until section 11.3), FAIL. A retake before retakeAt answers 429 code 4290 with data.retakeAt. Once the APPROPRIATENESS block is approved (the level was granted) a further attempt answers 409 code 4092; so does an attempt while the block is SUBMITTED for our compliance, and (revision 14) an attempt while the compliance lock stands (data.error MIFID_BLOCKS_REJECTED, the introduction of this section).

A legal entity (revision 8). The answers are given by a named representative on the entity's behalf: the body carries representativePersonId, the personId of an active REPRESENTATIVE of the file (from the kyb.persons of the onboarding answer, 9.7), required for a LEGAL client ("representativePersonId must name an active representative of the entity.") and refused on a NATURAL client ("representativePersonId applies to legal entities."). On this route and on 11.3 the refusal is a plain 400 code 4000 with the sentence as msg, like the route's other refusals; on PUT .../mifid (11.4) it is the field representativePersonId of the validation map. The assessment engine is unchanged; the person who answered is recorded on the entity file (APPROPRIATENESS_ANSWERED) and in our audit trail.

11.3 POST /partner/v1/clients/{clientId}/appropriateness/acknowledge

Scope TRADE. For a WARN result: the partner attests that the warning text was shown to the client and accepted. Body {version, acknowledgedAt, locale, textHash, representativePersonId}: version the version of the result you acknowledge (below), acknowledgedAt Unix ms, required, not in the future, locale and textHash the words your user read (below). The row carries our server time as the acknowledgement time and yours as the attested time.

{"version": 1, "acknowledgedAt": 1788311280000, "locale": "en", "textHash": "sha256:40e4befc4a2b55ba1eb2c2b33c302af867243e212fe6f38e151ca290a80cfc32"}

{"code": 0, "data": {"version": 1, "acknowledgedAt": 1788311300000, "attestedAt": 1788311280000, "outcome": "WARN", "verificationLevel": "MICA_MIFID", "granted": true, "grantRefusal": null}}

400 code 4000 when there is no WARN result to acknowledge or acknowledgedAt is missing; 409 code 4092 while the compliance lock stands (revision 14, the introduction of this section: a repeated acknowledgement never re-runs the grant around a block our compliance rejected). A legal entity acknowledges through its named representative (representativePersonId, the rule of 11.2; recorded as APPROPRIATENESS_ACKNOWLEDGED on the file); grantRefusal as in 11.2.

version on the acknowledgement: REQUIRED from the cut over (revision 17). Announced in revision 15 and in force with the code of this revision, with the same cut over as 11.2 (production from its first day, the development environment from 2026-11-01 00:00 UTC): a body where version is absent or not a JSON integer answers 400 code 4000 "version (the version of the result you acknowledge, a JSON integer) is required."; before that instant an omission is accepted as before. It is ACCEPTED when it equals the version of the result you acknowledge OR that result's submittedVersion (the number you rendered inside a scoring-only acceptance, 11.2), so a client that sends the version it rendered is never refused by a switch it did not see. Anything else answers 409 code 4092 "The acknowledgement names another questionnaire version than the result it acknowledges." with data {error: "APPROPRIATENESS_ACK_VERSION_MISMATCH", resultVersion, submittedVersion} and NEVER currentVersion (a 409 that carries currentVersion means "re-read and re-render"; this one means "acknowledge the result you have"). The answer carries version, the result's. locale and textHash are taken under the SAME rules as on 11.2 against the RESULT's version, after the version comparison, with one addition: the textHash the 200 of 11.2 answered (the words your user was shown with the result) is always accepted. A refusal of this route consumes nothing (the attempts rule of the introduction of this section) and the next call carries a new Idempotency-Key.

11.4 PUT /partner/v1/clients/{clientId}/mifid

Scope TRADE, reliance APPROVED. The four MiFID blocks, all required, validated like the wizard and approved under the partner's attestation; errors are keyed mifid.<section>.<field>.

accountPurpose (ACCOUNT_PURPOSE): primary_purpose (one of long_term_investment, short_term_speculation, hedging, income_generation, portfolio_diversification, professional_trading, other), primary_purpose_other (required with other, at most 200).

employmentFinancial (EMPLOYMENT_FINANCIAL): employment_status (one of employed_full_time, employed_part_time, self_employed, unemployed, retired, student, homemaker, other), employment_status_other (with other, at most 100); for the three employed statuses also industry (one of agriculture_forestry, automotive, banking_financial, construction_real_estate, consulting, defense_aerospace, education, energy_utilities, entertainment_media, government_public, healthcare_pharma, hospitality_tourism, information_technology, insurance, legal_services, manufacturing, mining_metals, non_profit, retail_consumer, shipping_logistics, telecommunications, transportation, other), industry_other, position (one of entry_level, mid_level, senior, manager, director, vice_president, c_suite, board_member, owner_founder, other), position_other, employer_name (at most 100); always annual_income (one of lt_10k, 10k_25k, 25k_50k, 50k_100k, 100k_250k, 250k_500k, 500k_1m, gt_1m), net_worth (one of lt_50k, 50k_100k, 100k_250k, 250k_500k, 500k_1m, 1m_5m, gt_5m), expected_deposit_12m (one of lt_5k, 5k_10k, 10k_25k, 25k_50k, 50k_100k, 100k_500k, gt_500k).

sourceOfWealth (SOURCE_OF_WEALTH): three arrays of at least one distinct token each, with a free text (at most 200) required when other is chosen: income_sources / income_source_other (tokens employment_salary, business_income, investments, trust_income, rental_income, pension_retirement, government_benefits, family_support, other); funds_sources / funds_source_other (the income tokens plus inheritance_gift, savings, property_sale, business_sale, insurance_payout, legal_settlement); wealth_sources / wealth_source_other (employment_income, business_profits, investment_returns, property_ownership, inheritance, family_wealth, sale_of_assets, legal_settlement, other).

declarationsMifid (DECLARATIONS_MIFID): three booleans, every one true: order_execution_policy_consent, complex_products_risk_acknowledged, client_categorisation_notice_acknowledged. Before you send them, show the client the CURRENT versions of our Order Execution Policy, our Risk Disclosure (including its complex products section) and our Client Categorisation Notice at the links we publish to you (the versions our consent register records; we announce a new version before it takes effect); the client's acknowledgement in your interface is your evidence under your attestation.

The sentences the three keys stand for (revision 15, served since revision 18). Each key is the client's acknowledgement of one sentence of the regulated text family DECLARATIONS_MIFID, served by GET /partner/v1/texts?family=DECLARATIONS_MIFID (11.7) with the language members of 11.1, a textRevision and a textHash. THE READ IS THE TRUTH: render what GET /texts serves, never this table; a sentence may change at any instant by an approval of our compliance function, in force at the instant (no notice period, the content rule of section 21), the event appropriateness_test.text_changed with family DECLARATIONS_MIFID (16.4) is the signal to re-read and to drop your cache, and the display duty of section 8 (render as served, never rephrase, translate or shorten) applies to the served revision. The three sentences are printed here AS SERVED AT THIS PUBLICATION: revision 1 of master version 1, byte for byte the wording our compliance function approved on 2026-09-09 and our own onboarding shows, with the hash sha256:c04b33d65088c08d79bb62a3333d0741c098c541885e18f92e20ec50ecbaeafe; the text ids of revision 15 stay as the label of revision 1 (text id declarations_mifid.<key>.2026-09-09 = master version 1, revision 1). The sentence behind complex_products_risk_acknowledged, held in revisions 15 to 17 pending a re-confirmation, is printed from this revision: it is revision 1 as served, and our compliance function edits it, like the other two, in our own tooling.

declarationsMifidText (revision 18). An OPTIONAL top level object beside the four blocks and representativePersonId, {locale, textHash}: the locale and textHash of the GET /texts?family=DECLARATIONS_MIFID read you rendered to the user before the user acknowledged the three keys. It sits beside declarationsMifid, not inside it, because declarationsMifid is the block's data, stored and echoed as the three booleans. The rules are those of 11.2's locale and textHash, with the family's own labels; every 400 is a field of this route's validation map (mifid.declarationsMifidText.locale or .textHash, the label the first word of the field's sentence) and data.error carries the label of the first text refusal beside errors (additive), so key on data.error:

The checks run after the block validation and before any write; nothing is written by a refusal, and the Idempotency-Key claim is kept like every text refusal of 11.2. Every acknowledgement is RECORDED with the revision and the hash of the words (one record per call, in the same transaction as the blocks); a record stands as a declaration to those words, for ever, and nothing is invalidated by a later revision. The 200 carries declarationsText {family, masterVersion, locale, localeAssumed, textRevision, textHash, textAttested, recordedAt} (additive), and GET .../verification (11.5) the latest record. Send declarationsMifidText always: as long as the family is served in English only it is optional, and once a second language is served it is required by content exactly like 11.2's members (section 21, item (5)).

{
  "accountPurpose": {"primary_purpose": "long_term_investment"},
  "employmentFinancial": {"employment_status": "employed_full_time", "industry": "information_technology", "position": "senior", "employer_name": "Acme GmbH", "annual_income": "50k_100k", "net_worth": "100k_250k", "expected_deposit_12m": "5k_10k"},
  "sourceOfWealth": {"income_sources": ["employment_salary"], "funds_sources": ["savings"], "wealth_sources": ["employment_income"]},
  "declarationsMifid": {"order_execution_policy_consent": true, "complex_products_risk_acknowledged": true, "client_categorisation_notice_acknowledged": true},
  "declarationsMifidText": {"locale": "en", "textHash": "sha256:c04b33d65088c08d79bb62a3333d0741c098c541885e18f92e20ec50ecbaeafe"}
}

{
  "code": 0,
  "data": {
    "clientId": 412, "clientUid": "BARR-00000412", "verificationLevel": "MICA", "lifecycleState": "ACTIVE", "granted": false, "grantRefusal": null,
    "appropriateness": {"version": null, "outcome": null, "score": null, "takenAt": null, "acknowledgedAt": null, "retakeAt": null, "requiresAcknowledgement": false, "attempt": 0},
    "requirements": {"TRADE:PERP": ["APPROPRIATENESS"], "TRADE:SPOT": [], "TRADE:BARRIER": ["APPROPRIATENESS"], "TRADE:STAKING": ["APPROPRIATENESS"], "DEPOSIT:CRYPTO": [], "WITHDRAW:CRYPTO": [], "DEPOSIT:FIAT": ["BANK_ACCOUNT"], "WITHDRAW:FIAT": ["BANK_ACCOUNT"]},
    "declarationsText": {"family": "DECLARATIONS_MIFID", "masterVersion": 1, "locale": "en", "localeAssumed": false, "textRevision": 1, "textHash": "sha256:c04b33d65088c08d79bb62a3333d0741c098c541885e18f92e20ec50ecbaeafe", "textAttested": true, "recordedAt": 1788307300000}
  }
}

All four blocks, every time. No partner route submits one MiFID block alone: PUT .../mifid takes all four on every call, and a missing section is a field error of the validation map. The four blocks are written and approved in one step BEFORE the grant is attempted and whatever the appropriateness outcome, so a client whose result is a FAIL or still missing holds the four blocks APPROVED while its level stays MICA. A REPEAT call rewrites all four blocks as a new version and approves them again under your attestation, EXCEPT while our compliance function holds the file (revision 14, the introduction of this section): a block it set REJECTED locks the route until it releases the block, and blocks SUBMITTED for its decision lock the route until it decides; both answer 409 code 4092 and write nothing. The grant is attempted only while the client's level is MICA (a client already at MICA_MIFID keeps its level), and a result completed after more than two attempts hands the file to our compliance instead of granting. This is also the one way to put the SOURCE_OF_WEALTH block on file for a client you kept at level MICA who met the enhanced due diligence ask of 15.1: send the full four-block body.

A legal entity (revision 8). The body carries representativePersonId (the rule of 11.2: the representative who attests the blocks on the entity's behalf, recorded as MIFID_ATTESTED on the file). The four blocks keep their shapes and are read with entity semantics: accountPurpose is the entity's purpose; employmentFinancial describes the entity: employment_status other with employment_status_other "legal entity", industry the entity's token, position the representative's position, employer_name the legal name, annual_income the entity's net annual revenue band, net_worth the entity's net assets band, expected_deposit_12m as for a natural person; sourceOfWealth the entity's sources (business_income, business_profits, investment_returns, ...); declarationsMifid acknowledged by the representative; a missing or invalid representativePersonId (or one sent for a natural person) is the field representativePersonId of the same validation map as the block errors. The grant needs the LEI in good standing (MiFIR Article 26(6)): a leiStatus of ISSUED, PENDING_TRANSFER or PENDING_ARCHIVAL (the GLEIF registration status), FORMAT_OK (the format check alone, when no registry lookup is configured) or UNKNOWN (the lookup could not run, failed, or answered a status we do not know: the format check stands until the next check re-reads the registry); a LAPSED, RETIRED, ANNULLED, DUPLICATE, MERGED or invalid LEI leaves the level at MICA and the answer's grantRefusal says so ("KYB: a legal entity needs an LEI in good standing before it may trade MiFID instruments (MiFIR Article 26(6))"); renew the LEI, send the new one through PUT .../kyc (10.1) and the next assessment or acknowledgement attempts the grant again. Level MICA_MIFID unlocks the same families as for a natural person.

FORMAT_OK grants only when no registry lookup is configured (revision 10). Where our registry lookup runs, the grant looks the LEI up first: an LEI whose status is FORMAT_OK or has never been checked against the Global LEI System is checked ONCE at the grant, on every grant path (the assessment, the acknowledgement and PUT .../mifid alike), the status recorded on the file, and the answer of the registry decides: ISSUED, PENDING_TRANSFER, PENDING_ARCHIVAL and UNKNOWN (the registry unreachable) grant, LAPSED, RETIRED, ANNULLED, DUPLICATE, MERGED and an invalid LEI refuse with the sentence above in grantRefusal. A status already looked up is never re-fetched at the grant. The check runs at onboarding and at every new LEI, so a partner normally never sees the grant wait for it.

AFTER THE GRANT (revision 10, grown in place; the lapse sweep): where our registry lookup runs, our re-check of an approved entity's LEI runs at least every 30 days. An LEI whose registration is found LAPSED puts the client in close-only mode on perpetuals, barrier contracts and staking swaps 30 days after the lapse unless it is renewed in the meantime (the cure window); an LEI whose registration is RETIRED, ANNULLED, MERGED, DUPLICATE or no longer found puts the client in close-only mode at once. The pause is a restriction, not a lifecycle state: the client row keeps its lifecycleState (an ACTIVE client stays ACTIVE, and state=RESTRICTED on the clients list never finds a paused entity). In close-only mode an opening order, a barrier request, the accept of an opening request and a swap take answer the close-only sentence of section 4 as 400 code 4000 ("Your account is in close-only mode on this market: you can reduce or close positions but not open new ones. Please contact support."), reducing and closing always go through, and crypto spot is unaffected. You learn of the pause and of its end as margin.restriction_set and margin.restriction_lifted (16.4); there is no other wire change, and leiStatus on the client row and on kyb reads the stored registration status throughout. The client is mailed the notice and, where the registry publishes the renewal date, renewal reminders. Send the renewed LEI through PUT .../kyc (10.1): it is checked at once, and a registration found ISSUED or pending again lifts the pause on the next pass; a registry that cannot answer neither starts nor lifts a pause. Off on the development environment (section 18).

11.5 GET /partner/v1/clients/{clientId}/verification

The client-shaped overview: level, lifecycle, every block with its status and the ROLE of its decider (PARTNER for your own attestations, SYSTEM for our automation, else the role of our employee: COMPLIANCE, ADMIN, ...; never a person's name, revision 6), the requirements map, the latest appropriateness result and the package summary.

{
  "code": 0,
  "data": {
    "clientId": 412, "clientUid": "BARR-00000412", "partnerClientRef": "cust-001", "level": "MICA_MIFID", "lifecycleState": "ACTIVE",
    "blocks": [
      {"code": "PERSONAL_INFO", "level": "MICA", "status": "APPROVED", "decidedBy": "PARTNER", "decidedAt": 1788307300000, "reason": null, "updatedAt": 1788307300000},
      {"code": "APPROPRIATENESS", "level": "MICA_MIFID", "status": "APPROVED", "decidedBy": "PARTNER", "decidedAt": 1788311200000, "reason": null, "updatedAt": 1788311200000}
    ],
    "requirements": {"TRADE:PERP": [], "TRADE:SPOT": [], "TRADE:BARRIER": [], "TRADE:STAKING": [], "DEPOSIT:CRYPTO": [], "WITHDRAW:CRYPTO": [], "DEPOSIT:FIAT": ["BANK_ACCOUNT"], "WITHDRAW:FIAT": ["BANK_ACCOUNT"]},
    "appropriateness": {"version": 1, "outcome": "PASS", "score": 24, "takenAt": 1788311200000, "acknowledgedAt": null, "retakeAt": 1788397200000, "requiresAcknowledgement": false, "attempt": 1, "submittedVersion": null, "supersededBy": null, "locale": "en"},
    "kycPackage": {"kycPackageId": 61, "revision": 2, "status": "ACCEPTED", "reviewNote": null},
    "declarationsText": {"family": "DECLARATIONS_MIFID", "masterVersion": 1, "locale": "en", "localeAssumed": false, "textRevision": 1, "textHash": "sha256:c04b33d65088c08d79bb62a3333d0741c098c541885e18f92e20ec50ecbaeafe", "textAttested": true, "recordedAt": 1788307300000}
  }
}

Since revision 18 the answer carries declarationsText, the LATEST record of the declarations the client acknowledged (11.4: the family, the master version, the locale and whether it was assumed, the revision and the hash of the words, whether you attested the hash, the instant; null before the client's first MiFID write). Since revision 17 the appropriateness object carries submittedVersion, supersededBy and locale as the 200 of 11.2 answered them (the number rendered inside a scoring-only acceptance, the version in force when the attempt was scored under the previous one, the language of the words the client read; the same three members on PUT .../mifid's answer).

Block statuses: NOT_STARTED, DRAFT, SUBMITTED, APPROVED, REJECTED, EXPIRED. The twelve blocks listed are the seven MiCA blocks (PERSONAL_INFO, IDENTIFICATION, TAX_RESIDENCY, FATCA, PEP, DECLARATIONS_MICA, IDENTITY_CHECK) and the five MiFID blocks (ACCOUNT_PURPOSE, EMPLOYMENT_FINANCIAL, SOURCE_OF_WEALTH, APPROPRIATENESS, DECLARATIONS_MIFID). A legal entity (revision 8) lists four more with level: "KYB": ENTITY_INFO, ENTITY_DOCUMENTS, UBO_DECLARATION, REPRESENTATIVES (the entity file, APPROVED with the MiCA grant); a natural person's answer is unchanged.

EXPIRED belongs to the block model this read shares with our own onboarding. It is set only on IDENTITY_CHECK, and only for a client of our own hosted identity flow whose identity session expired or was abandoned before it was completed. It cannot occur for a client you onboarded: your identityCheck record is stored as a session that is already concluded (9.3). No block of your client expires by time: a block leaves APPROVED only by a decision of our compliance, which sets it REJECTED and says why in reason (16.4). What runs after onboarding is described in 10.6.

On the five MiFID blocks two statuses mean that our compliance function holds the file (revision 14, the introduction of section 11): REJECTED with the role of our employee in decidedBy is the compliance lock (your MiFID writes answer 409 until our compliance releases the block, which then reads DRAFT with decidedBy null and the sentence kept in reason), and SUBMITTED is a file waiting for its decision (a result completed after more than two attempts). A REJECTED APPROPRIATENESS block with decidedBy null is a failed attempt of the client and locks nothing.

requirements is also the one advance signal of the enhanced due diligence source-of-wealth ask (15.1): once it applies to the client, requirements["DEPOSIT:CRYPTO"] and requirements["WITHDRAW:CRYPTO"] list SOURCE_OF_WEALTH. The read carries no enhanced due diligence standing (no threshold, no deposit sum, no flag), so you cannot read how close a client is to the threshold.

The read has no restrictions member. A client restriction (NO_NEW_ORDERS, CLOSE_ONLY, NO_WITHDRAWALS, FROZEN; an information-only kind without any trading or money effect exists too, so an event need not be followed by a refusal) cannot be read on this API today: not its kind, not its family, not its ground. You learn that one was engaged or lifted from margin.restriction_set and margin.restriction_lifted (16.4), which carry the restriction's id only, and you meet its effect as the sentence of the refused request (11.4, 15.1). GET /trading-status (12.1) answers the venue-wide trading halts, never a client's restrictions.

Lifecycle states a partner sees: KYC_PENDING (held for review), ACTIVE, RESTRICTED (the account is held pending a decision of our compliance, for example after a KYC revision that changed the client's identity and whose re-screening needs a decision, 10.1; opening new risk is refused), KYC_REJECTED, CLOSED. A client restriction is NOT a lifecycle state: a close-only pause (the LEI pause of 11.4, the identity document pause of 10.6) or any other restriction leaves lifecycleState as it was, so an ACTIVE client under a restriction still reads ACTIVE.

11.6 Client categorisation (professional clients)

Every client is onboarded as RETAIL (9.1). A client who asks to be treated as a PROFESSIONAL client (MiFID II Annex II) asks in writing, and you record that request on the client's behalf; OUR compliance function assesses the file and decides in our back office. No partner route decides, applies or revokes a categorisation. Since revision 10 the decision also needs the written request to be GENERAL (criteria.scope GENERAL; a request scoped to particular products is still recorded and read back as sent, but it is never approved: we hold one categorisation per client), criteria.warningVersion to name the published warning version the client read (CAT-WARN-2026-09 v1 today; our officer tells you the version in force at onboarding and on every change) and statementSignedAt to lie at or after warningShownAt. The outcome reaches you as the webhook client.categorization_changed (16.4) and changes categorization on every read; the leverage caps (12.3: the schedule for the categorisation in force) and the retail protections (the negative balance protection among them) follow the categorisation in force. An opt-down back to RETAIL is a request of the same shape and is applied at once on approval (a client may always ask for more protection). Eligible counterparties have no path.

Two bases exist:

POST /partner/v1/clients/{clientId}/categorization

Scope TRADE, reliance APPROVED (403 code 4036 otherwise, like the onboarding, KYC and MiFID writes: the written request, the warning and the statement are records you hold), Idempotency-Key recommended. Records the client's request: requestedBy CLIENT, the requester your partner code. Answer 201 with the request.

{
  "target": "PROFESSIONAL",
  "basis": "ELECTIVE",
  "criteria": {"tradesPerQuarter": [14, 12, 9, 11], "portfolioEur": "620000", "financialSectorMonths": 30, "financialSectorRole": "derivatives trader at a bank",
               "qualitativeAssessment": "the client has run a discretionary derivatives book for two years", "scope": "GENERAL", "assessedPerson": null, "notes": null,
               "warningVersion": "CAT-WARN-2026-09 v1", "statementRef": "sig-88a1"},
  "evidence": [{"kind": "TRADE_HISTORY", "description": "quarterly trade counts from the partner's records", "ref": "acme/trades/2025Q3-2026Q2"},
               {"kind": "PORTFOLIO_PROOF", "description": "custody statement of 2026-08-31", "ref": "doc-412-7"}],
  "requestReceivedAt": 1788300000000, "warningShownAt": 1788300100000, "statementSignedAt": 1788300200000,
  "perSe": null
}

Validation failures answer 400 code 4000 with data.errors (a map of field paths to one sentence each, like 9.1: target, basis, criteria, criteria.qualitativePass, perSe, evidence, requestReceivedAt, ...); nothing is recorded. One request is open per client at a time: a second POST answers 409 code 4092 "a categorisation request is already open for this client" with data.requestId.

The request on the wire (every read of this section):

{
  "code": 0,
  "data": {
    "requestId": 77, "clientId": 412, "clientUid": "BARR-00000412", "partnerClientRef": "cust-001",
    "requestedBy": "CLIENT", "requester": "PARTNER", "basis": "ELECTIVE", "from": "RETAIL", "target": "PROFESSIONAL",
    "criteria": {"tradesPerQuarter": [14, 12, 9, 11], "portfolioEur": "620000", "financialSectorMonths": 30, "financialSectorRole": "derivatives trader at a bank",
                 "qualitativeAssessment": "the client has run a discretionary derivatives book for two years", "scope": "GENERAL", "requestChannel": "partner:NEOBROKER1", "warningVersion": "CAT-WARN-2026-09 v1", "statementRef": "sig-88a1"},
    "perSe": null,
    "evidence": [{"kind": "TRADE_HISTORY", "description": "quarterly trade counts from the partner's records", "ref": "acme/trades/2025Q3-2026Q2", "addedBy": "PARTNER", "addedAt": 1788300300000},
                 {"kind": "PORTFOLIO_PROOF", "description": "custody statement of 2026-08-31", "ref": "doc-412-7", "addedBy": "PARTNER", "addedAt": 1788300300000}],
    "requestReceivedAt": 1788300000000, "warningShownAt": 1788300100000, "statementSignedAt": 1788300200000,
    "status": "PENDING", "decidedBy": null, "decidedAt": null, "effectiveAt": null, "appliedAt": null, "reviewAt": null, "noticeSentAt": null,
    "revokedBy": null, "revokedAt": null, "createdAt": 1788300300000, "updatedAt": 1788300300000,
    "assessment": {"basis": "ELECTIVE", "tradesMet": true, "quartersMeeting": 3, "tradesTotal": 46, "tradesAverage": 11.5, "portfolioMet": true, "experienceMet": true, "quantitativeMet": 3, "quantitativePass": true,
                   "qualitativePass": false, "requestReceived": true, "warningShown": true, "statementSigned": true, "complete": false,
                   "missing": ["qualitative assessment: expertise, experience and knowledge not assessed as adequate (qualitativePass)"],
                   "perSe": null}
  }
}

status is PENDING (with us), APPROVED (approved, the 24 hour cooling period runs until effectiveAt; the client may still withdraw), APPLIED (in force since appliedAt; reviewAt the date of our periodic review), REJECTED, WITHDRAWN or REVOKED (revokedAt). requester, decidedBy and revokedBy are role labels (PARTNER, SYSTEM, or the role of our employee: COMPLIANCE, ADMIN), never a person's name; our officer's decision reason does not cross this API. assessment is our router's evaluation of the file as recorded: quantitativePass (section II: two of three; on PER_SE two of the three size requirements, with perSe: {balanceSheetMet, netTurnoverMet, ownFundsMet, thresholdsMet} and the section II figures reading false), qualitativePass (ours; not required on PER_SE), the three procedural stamps, complete and missing (the sentences naming what our officer still needs; on PER_SE for example "per se test: 1 of 3 size requirements met, 2 required (balance sheet EUR 20,000,000, net turnover EUR 40,000,000, own funds EUR 2,000,000)").

GET /partner/v1/clients/{clientId}/categorization

The client's file: {clientId, clientUid, partnerClientRef, categorization, openRequest, appliedRequestId, reviewAt, requests: [...], annexII}, the requests newest first in the shape above, openRequest the PENDING or APPROVED one (else null), appliedRequestId and reviewAt of the professional status in force (both null while the client is RETAIL), annexII the thresholds (minTradesPerQuarter 10, minQuarters 4, minPortfolioEur 500000, minFinancialSectorMonths 12, minCriteriaMet 2, perSe: {minBalanceSheetEur, minNetTurnoverEur, minOwnFundsEur, minThresholdsMet}). An APPROVED request whose cooling period has passed is applied by our scheduler within a minute of effectiveAt (the webhook, the leverage caps and the retail protections follow the period whether or not anyone reads); this read applies it too, so a poll after the period never sees it unapplied.

POST /partner/v1/clients/{clientId}/categorization/{requestId}/withdraw

Body {reason} (required, at most 4000 characters). The client withdraws its request while it is PENDING or APPROVED and not yet applied (the cooling period): the request becomes WITHDRAWN and is answered; 409 code 4092 when it can no longer be withdrawn, 404 code 4004 for a request of another client. No webhook fires (you made the change).

What happens on our side. Our compliance officer reads the file in our back office (the queue shows the request "via NEOBROKER1"), may add evidence, records the qualitative assessment on an elective request, and decides. Approval of a professional request needs a complete file (the officer is told what is missing); the approval starts the cooling period (24 hours), within a minute of whose end the categorisation is applied by our scheduler (any read of the file applies it too), the client is mailed the notice of its new categorisation and the protections it loses or regains (to the contact address you gave us), and a review date is set (12 months). At the review date our officer confirms the status (a new reviewAt on the file, no webhook) or revokes it (the REVOKED webhook). A rejection, a revocation by our periodic review, or the client's written request through you as an opt-down request fires the same webhook. After the webhook read GET .../clients/{clientId} (the categorization in force) or the file.

11.6.1 The warning and the statement

The clear written warning of the protections lost (Annex II section II.2) is OUR published text, identified by its version. You show it to the client verbatim, in a durable medium, before the client signs; warningShownAt is the time you delivered it and criteria.warningVersion its identifier. A new version is announced to you before it takes effect; a request naming another version than the one in force stays PENDING until our officer records the published one or rejects the request. The version in force is CAT-WARN-2026-09 v1:

CAT-WARN-2026-09 v1. Warning to a client who asks to be treated as a professional client. PM MTF Ltd (barriers) treats you as a retail client today. If we agree to treat you as a professional client under MiFID II, you lose the protections that apply to retail clients: (1) the retail leverage limits: the retail leverage limit of each asset class no longer applies to you; on every perpetual contract we may offer you the higher leverage of our professional leverage schedule in force at the time, published on the leverage read of your account, so a small price move can cost you a larger part of your account; (2) the guaranteed margin close-out at 50 percent: as a retail client your open positions are closed by regulation when the margin on your account falls to 50 percent of the required margin; as a professional client that guarantee no longer applies and only our own risk rules protect you; (3) the negative balance protection: as a retail client your loss can never exceed the funds on your account; as a professional client you may owe us more than you deposited; (4) the standardised risk warning and the loss-percentage disclosure that retail clients receive; (5) the information and appropriateness treatment given to retail clients: we may give you less detailed information on the products, their risks and their costs, and we may assume that you have the experience and knowledge to understand the risks of the products and services you ask for, so the appropriateness assessment applied to retail clients no longer protects you. Investor compensation and complaints: as a professional client you may lose the cover of the Investor Compensation Fund for clients of Cyprus investment firms and access to the Financial Ombudsman of the Republic of Cyprus for complaints against us. You may ask at any time, in writing, to be treated as a retail client again. Read this warning in full before you sign the separate statement.

The client's separate written statement is collected as a SEPARATE document AFTER the warning (statementSignedAt at or after warningShownAt; your signature reference in criteria.statementRef), with this wording:

I have read warning CAT-WARN-2026-09 v1. I ask PM MTF Ltd to treat me as a professional client for all services and products. I understand that I lose the protections and any investor compensation rights listed in that warning and I am aware of the consequences. I will inform PM MTF Ltd of any change that could affect my categorisation.

The statement asks for the professional treatment for ALL services and products, which is why criteria.scope must read GENERAL: a client whose written request covers particular services or products only has not asked for what the statement says, and such a request is not approved.

11.7 GET /partner/v1/texts?family=&locale=

Since revision 18. The sentences of a regulated text family in the language served: today the MiFID declaration sentences, family DECLARATIONS_MIFID, the three sentences the keys of declarationsMifid (11.4) stand for. Authenticated like GET /appropriateness-test (the key, no client, no scope beyond it). family is REQUIRED and must name a sentences family we serve (an absent, unknown or other family answers 400 code 4000 with data.error TEXT_FAMILY_UNKNOWN and a sentence naming the families served); locale as on 11.1 (xx or xx-YY, _ for -, resolved to the primary language; a value that is no language tag 400 LOCALE_MALFORMED; Accept-Language is never read). The answer is served from the family's CURRENT English and ONE bundle, never a mix: the primary language requested when availableLocales lists it, else the English as a whole with localeFallback true and requestedLocale echoing what you sent. sentences[] is an ARRAY in the key order the client is shown, never a map. masterVersion is the version of the family's key set, fixed by code (1); a rewording is a new textRevision under it, announced by appropriateness_test.text_changed with family DECLARATIONS_MIFID (16.4). textHash is the hash of the words under the recipe of 11.1 (the lines of a sentences family); revision 1 hashes to sha256:c04b33d65088c08d79bb62a3333d0741c098c541885e18f92e20ec50ecbaeafe on every environment until our compliance function approves a later revision. Send the locale and textHash of the read you rendered as declarationsMifidText on PUT .../mifid (11.4). The caching rule of 11.1 applies PER FAMILY AND LOCALE: at most 5 minutes, drop the cache on any appropriateness_test.text_changed whose family is the family, an answer with localeFallback true never beyond minutes; render from this read when the user opens the declarations, never from a copy shipped with a release. The pseudo locale qps of section 18 is served here too on the development environment.

{
  "code": 0,
  "data": {
    "family": "DECLARATIONS_MIFID", "masterVersion": 1, "asOf": 1790845260000,
    "locale": "en", "requestedLocale": null, "localeFallback": false, "availableLocales": ["en"],
    "textRevision": 1, "textHash": "sha256:c04b33d65088c08d79bb62a3333d0741c098c541885e18f92e20ec50ecbaeafe",
    "sentences": [
      {"key": "order_execution_policy_consent", "text": "I have read the Order Execution Policy of PM MTF Ltd and I consent to it. ..."},
      {"key": "complex_products_risk_acknowledged", "text": "I have read the Risk Disclosure of PM MTF Ltd, including its section on complex products. ..."},
      {"key": "client_categorisation_notice_acknowledged", "text": "I have received and read the Client Categorisation Notice of PM MTF Ltd. ..."}
    ]
  }
}

The members locale, requestedLocale, localeFallback, availableLocales, textRevision and textHash mean what 11.1 says; asOf is our clock. The three sentences of revision 1 are printed in full in 11.4.

12. Trading

Every trading and account route delegates to the same code path as our own client API with the resolved client id, so the verification gate (403 code 4030 with missingBlocks), the TERMS re-consent gate beside it (403 code 4035 with {doc, currentVersion, gateFrom} on an opening order, a barrier request, the accept of an opening request and a swap take while our switch is on, section 10.5), the client restrictions, the market controls and every economic rule apply unchanged. Successful trading writes are attributed on the client's and the partner's audit streams. A venue transport failure answers 502 code 5020; the trading row usually stays in flight and our poll resolves it, so read the state back before retrying. A failure on our side after the venue answered answers the same way (an order state SENT, the other writes 502 code 5020 with the row id) and keeps the Idempotency-Key (section 5, revision 19). Since revision 23 a write whose outcome the venue could not confirm (its code 5000, or a 5xx without a venue code from a proxy between us and the venue: the write may still take effect) answers the same way, never as a refusal: an order state SENT, a barrier request or close request, an accept and a staking take 502 code 5020 with the row id; a cancel of an order or a request 502 code 5020 "The trading venue could not confirm whether the cancel took effect. Please check whether it is still open and cancel it again if it is.", the object unchanged until the venue's confirmation or our reconciliation moves it. The trading routes are the same under both custody models; under PARTNER custody the cash the risk engine margins is the collateral the partner reported (section 15), nothing else changes.

12.1 Market data (READ scope, no client)

GET /instruments (bare: {instruments: [{symbol, family, displayName, assetClass}]}), GET /ticker?symbol ({code, msg, data: {symbol, lastPrice, markPrice, indexPrice, bestBid, bestAsk, volume24h, openInterest, fundingRate, fundingRatePct, predictedFundingRate, nextFundingTs}, asOfSeq, ts}; volume24h null since revision 27, the 24 h volume below), GET /tickers (bare: {asOf, tickers: [{symbol, family, displayName, assetClass, lastPrice, markPrice, indexPrice, bestBid, bestAsk, change24h, change24hPct, high24h, low24h, volume24h, quoteVolume24h, openInterest, fundingRate, fundingRatePct, predictedFundingRate, nextFundingTs}]}, one row per offered market built member by member, so a row carries exactly these members and none of the other members the venue's ticker holds; a market whose venue ticker failed is listed with null prices, a BARRIER or SPOT row carries null funding members and nextFundingTs 0, a SPOT row a null openInterest, quoteVolume24h is null while no 1 hour candle of the last 24 hours could be read for the market, and volume24h is null on every row since revision 27), GET /klines?symbol&interval&from&to&limit ({code: 0, data: {symbol, interval, intervalMs, klines: [{t, open, high, low, close, volume, trades, partial}], hasMore, oldestAvailable, asOf}}; intervals 1m, 5m, 15m, 30m, 1h, 4h, 1d; limit 1 to 1000), GET /orderbook?symbol&depth (bare: {symbol, bids: [[price, qty]], asks: [[price, qty]], checksum, asOfSeq, ts}; depth 1, 5, 25 or 100), GET /market-trades?symbol&limit (bare: {symbol, trades: [{tradeId, price, qty, side, flags, ts}], asOfSeq, ts}), GET /index-price?symbol (bare: {symbol, indexPrice, ts}), GET /funding?symbol (bare: {symbol, fundingRate, fundingRatePct, predictedFundingRate, predictedFundingRatePct, fundingRateAnnualizedPct, fundingIntervalHours, settleCcy, nextFundingTs, funding: {schedule, ...}}), GET /market-info?symbol (bare: the market specification: enabled (the offered-instrument row) and, since revision 10 (BROKER-84), offered (our router currently offers the market; false while our operator disabled it, in which case a new opening order, a barrier request, the accept of an open barrier request and a swap take on it answer 400 code 4000 with "This market is not currently offered." while existing exposure stays closable), grids, limits, funding schedule, risk tiers, leverage schedule, unitLabel (since revision 11 read from the venue's published tick: the quantity unit when the venue's listing makes it other than one base asset unit, 1,000 JPY on the two JPY markets once the venue lists them at tickSize 0.0001, null while the venue lists 1 JPY at 0.000001, on every other market and while the venue is unreachable; GET /instruments carries it per row), the barrier parameters knockOutRebateBps / strictTakeProfitPremiumBps / strictTakeProfitOffered / barrierPremiumBps and, on a BARRIER market, barrierExpiry {maxExplicitMs, defaultLifeMonths, venueMaxLifeHours} (the 8 h cap on an explicit barrier.expiryTs, the 12-month open-end default when it is omitted, the venue's published maximum contract life in hours that clamps the default less 60 s, null on an older venue; the block is null on every other family), the commission (commissionBasis, commissionBps, commissionMin, commissionCurrency: since revision 10, grown in place by the operator decision OQ-36 D16 and BROKER-8, commissionBasis is PREMIUM on a BARRIER market, where commissionBps is basis points OF THE PREMIUM (the maximum loss the ticket and the preview show) and commissionMin the per-CONTRACT minimum, and NOTIONAL on PERP and SPOT (basis points of qty x price, commissionMin per order); commissionBps is a decimal number, 100 on the barrier markets and 0.1 on the perpetuals) and the venue fees, and since revision 10 (BROKER-95) on a barrier market the key information documents kid and kidStrict (the normal and the strict take profit contract): each {doc, version, title, url, sha256, effectiveAt, acknowledged} or null while no version with a file is in force, doc the consent document code KID_<SYMBOL> / KID_<SYMBOL>_STRICT, url the absolute public URL of the PDF on our router (no key needed, cached five minutes, throttled per address), sha256 the file's hash, acknowledged ALWAYS null on this read (no client rides along: read the client's acknowledgement rows on GET .../clients/{clientId}/consents); both null on every other family; fetch the PDF from url, show it in your interface and record the client's acknowledgement with POST .../clients/{clientId}/consents {doc, version} before the first request on the market, 10.5), GET /trading-status ({code: 0, data: {asOf, halted, halts: [{scope, since, until, message}]}}; a halt has no end time, so until is null; a halt our desk engaged with its sweep cancelled the clients' resting opening orders in scope, the neutral message says so and the order.canceled webhooks follow from the venue's confirmations, stop-loss and reducing orders stay), GET /currencies (bare: {cash: "USDC", currencies: [{code, kind, venueAsset, displayDecimals, scale}]}), GET /staking/markets and GET /staking/offers?asset&symbol (section 12.4).

Market families: PERP (perpetual swaps, BTC-USD-PERP, SP500-USD-PERP, ...), SPOT (prefunded cash markets, BTC-USD), BARRIER (knock-out contracts by RFQ, BTC-USD-KO), STAKING (writer-first swap markets, USD-TBILL-SWAP). A symbol that is not offered answers 400 code 4000 ("A market symbol is required.") or 404 code 4004.

THE 24 H VOLUME (revision 27). The venue's ticker figure that volume24h carried is not a 24 hour volume: it is the traded base quantity of every trade since the venue's gateway process last started, and it never drops a trade older than 24 hours, so it restarts with each venue restart and can differ between venue nodes. Since this revision we serve volume24h as null on GET /ticker (every other member of data as the venue sent it) and on every row of GET /tickers, until the venue's rolling 24 hour window is live on the environment you use; that return is a later revision of this reference. quoteVolume24h on GET /tickers is unchanged: the traded value of the last 24 hours summed from the venue's 1 hour candles (candle volume x candle close), an approximation of the USD turnover, and null while no candle of that window could be read for the market. Read the traded value from quoteVolume24h, and show no base 24 hour volume while volume24h is null.

12.2 Barrier contracts by RFQ

A barrier contract is bought by request for quote: the client names the market, side, size, knock-out level, optional take profit and expiry; market makers quote an entry price; the client (or the router on the client's behalf, autoAccept, default true) accepts a quote and the contract opens. The premium (the maximum loss) is a share of the entry-to-barrier distance (premiumBps); the contract ends AT the barrier (KNOCK_OUT), AT the take profit (TAKE_PROFIT), at expiry, or early by a close request.

Every step of that life reaches your webhook as well (section 16.4): rfq.quote once per live quote, rfq.accepted when the request traded, rfq.expired, rfq.canceled or rfq.rejected when it ended without trading, and barrier.closed when the contract ended; the reads of this section stay the state to converge on.

POST /clients/{clientId}/rfq (TRADE, Idempotency-Key), body RfqRequest:

Two consent refusals of the request since revision 10 (BROKER-95, BROKER-96; section 4; both 403 code 4035 with a distinct data.error, both over FIX as 297=5 9110=4035 with the sentence in Text(58)): the KEY INFORMATION DOCUMENT gate, on the opening request of a RETAIL client only (the preview, the accept, the cancel and the early close are never gated; a PROFESSIONAL client passes): without an acknowledgement of the market's current document (kid of 12.1, kidStrict on a strict request) the answer is {code: 4035, msg: "Please read and acknowledge the key information document for this market (KID_BTC_USD_KO, version 2026-09) before your first request.", data: {error: "KID_REQUIRED", doc: "KID_BTC_USD_KO", currentVersion: "2026-09", symbol: "BTC-USD-KO", strict: false}}, and while no document is published at all msg: "The key information document for this market is not available yet, so this contract cannot be requested by retail clients." with currentVersion null (a strict request without the strict document reads this with doc the _STRICT code); record the acknowledgement with POST .../consents {doc, version} (10.5) after showing the PDF from url. The STRICT CONSENT gate, on a strict take profit request and its preview: while the client's standing on RISK_DISCLOSURE is older than the version in force the answer is {code: 4035, msg: "Accept the current Risk Disclosure before requesting a strict take profit contract.", data: {error: "RISK_DISCLOSURE_CONSENT_REQUIRED", doc: "RISK_DISCLOSURE", currentVersion: "2026-09"}}; a normal request is never gated; inert while no version of the document is registered; record the acceptance with the same POST (our CRM can too). Since revision 10 (section 15.7) an opening request and the accept of an opening request are also refused with 403 code 4041 PARTNER_CLOSE_ONLY (data: {error: "PARTNER_CLOSE_ONLY"}, the sentence in msg) while your clients are close-only under the settlement tier; a close request and its accept never.

Answer 200 {code: 0, data: <rfq>}:

{
  "code": 0,
  "data": {
    "rfqId": 311, "clientId": 412, "clientUid": "BARR-00000412", "venueRfqId": 5207, "clOrdId": "BARR-RFQ-311",
    "symbol": "BTC-USD-KO", "side": "BUY", "direction": "LONG", "qty": "1.0", "barrierLevel": "63000.0", "takeProfit": "66500.0",
    "expiryTs": 1819843200000, "expiryDefaulted": true, "expiresAt": 1788311460000, "expiresInMs": 59200,
    "state": "OPEN", "createdAt": 1788311400000, "updatedAt": 1788311400000, "rejectReason": null,
    "accepting": false, "autoAccept": true, "autoAcceptNote": null, "closeContractId": null, "contractEntry": null,
    "acceptedQuoteId": null, "contractId": null, "entryPrice": null,
    "commission": "0.000000", "maxLossAtRequest": "2222.130000", "premium": "2222.130000", "markAtRequest": "65469.0",
    "impliedLeverage": "26.51", "potentialProfit": "1031.000000", "strictTakeProfit": false, "premiumBps": 9000,
    "quotes": [], "currency": "USDC",
    "channel": "REST", "channelKeyId": null, "channelRef": null
  }
}

channel, channelKeyId and channelRef (additive, revision 9): the transport that made the request, REST for every request of these routes and FIX for a request entered on a FIX session (section 20, docs/14 section 7), with the key of that session (the keyId of GET /me) and the QuoteReqID(131) the session sent; REST with two nulls otherwise. An early close requested over FIX carries them the same way.

Request states: OPEN, ACCEPTED (a contract opened, contractId, entryPrice, acceptedQuoteId), CANCELLED, EXPIRED, REJECTED (rejectReason). Errors: 400 code 4000 (the barrier floor "The barrier must be at least 0.1 percent away from the current price (1000x maximum).", the lot grid, the minimum quantity and, since revision 12, the minimum request value "The request value is below the minimum for this market (100.00 USD)." (refused before anything is written: no data, no rfqId, no rfq.rejected webhook; the preview answers accepted: false with the sentence as reason), the window, the account state, the free-margin check), 403 code 4030, 404 code 4004 ("This market is not offered."), 502 code 5020 (data.rfqId names the row, it stays OPEN and the poll resolves it). A request the VENUE refused for its minimum (the mark moved between our check and the venue, or a quote priced below the mark, since the venue values the request at the mark but every quote at its entry) ends REJECTED with the same sentence as rejectReason, 400 code 4000 with data {rfqId, state: "REJECTED"} and the rfq.rejected webhook, as any venue refusal. A fractional request on the served grid is an ordinary request: {"symbol": "BTC-USD-KO", "side": "BUY", "qty": "0.05", "barrier": {"level": "63000"}} answers the <rfq> above with qty: "0.05" and the per-unit figures scaled by 0.05 (premium: "111.106500" at the example's mark), while the same body with qty: "0.001" (65.47 USD at that mark) answers {"code": 4000, "msg": "The request value is below the minimum for this market (100.00 USD).", "error": "The request value is below the minimum for this market (100.00 USD)."} and writes nothing.

POST /clients/{clientId}/rfq/preview: the same body, nothing written; {accepted, reason, mark, maxLoss, premium, estimatedCommission, estimatedCloseCommission, requiredFreeMargin, freeMarginBefore, freeMarginAfter, impliedLeverage, potentialProfit, maxLeverage, expiryTs, expiryDefaulted, strictTakeProfit, premiumBps, knockOutRebateBps, strictTakeProfitPremiumBps, strictTakeProfitOffered, currency}. estimatedCommission is the client's BARRIER scheme applied to the PREMIUM (basis points of the premium, ceiled to the micro, at least the per-contract minimum; revision 10, OQ-36 D16), estimatedCloseCommission the early-close commission estimated at the same reference and reserved with the contract while it is open (revision 10, BROKER-14), and requiredFreeMargin = premium + estimatedCommission + estimatedCloseCommission. A venue transport failure while the preview reads the market's live facts answers 502 code 5020 (nothing was written; retry); POST .../margin/preview (section 12.3) answers the same (revision 6).

GET /clients/{clientId}/rfq: the client's live requests with their quotes ({rfqs: [<rfq with quotes>]}). A quote: {quoteId, price, qty, validUntil, validForMs, impliedMaxLoss, impliedPremium, impliedLeverage, impliedPotentialProfit, impliedPnl, state, acceptable, notAcceptableReason}; quote states LIVE, EXPIRED, WITHDRAWN (the maker pulled it), ACCEPTED (the one that traded), SUPERSEDED (still valid when another quote of the request was accepted).

GET /clients/{clientId}/rfq/{rfqId}: one request.

POST /clients/{clientId}/rfq/{rfqId}/accept (TRADE, Idempotency-Key), body {quoteId}: the manual accept when autoAccept was false. The pre-trade check runs again at the quoted entry, the accept goes to the venue and the contract opens:

{
  "code": 0,
  "data": {"rfqId": 311, "venueRfqId": 5207, "quoteId": 902, "contractId": 4711, "tradeId": 771310, "symbol": "BTC-USD-KO", "side": "BUY", "direction": "LONG", "qty": "1.0", "entry": "65471.5", "barrierLevel": "63000.0", "takeProfit": "66500.0", "expiryTs": 1819843200000, "maxLoss": "2224.350000", "premium": "2224.350000", "leverage": "26.49", "potentialProfit": "1028.500000", "commission": "22.243500", "strictTakeProfit": false, "premiumBps": 9000, "ts": 1788311428000, "currency": "USDC"}
}

400 code 4000 when the request is not open, an accept is in flight or the quote is not acceptable, and, since revision 10 (BROKER-84), 400 code 4000 with "This market is not currently offered." on the accept of an OPENING request whose market our operator withdrew (manual and automatic; over FIX 35=j 380=0 with 9110=4000; a close request and its accept never); 403 code 4041 PARTNER_CLOSE_ONLY on the accept of an opening request while your clients are close-only under the settlement tier (15.7; the accept of a close request is never refused for it); 404 code 4004 for an unknown request or a gone quote; 502 code 5020 with data: {rfqId, quoteId, accepting: true} (the poll resolves it).

POST /clients/{clientId}/rfq/{rfqId}/cancel (TRADE): {rfqId, state: "CANCELLED"}.

GET /clients/{clientId}/barriers?state&limit&before: state open (default) or history; limit 1 to 500; {barriers: [...], hasMore, nextBefore, currency}. An open contract is valued live:

{
  "contractId": 4711, "symbol": "BTC-USD-KO", "side": "LONG", "qty": "1.0", "entry": "65471.5", "barrierLevel": "63000.0", "takeProfit": "66500.0",
  "expiryTs": 1819843200000, "expiresInMs": 31531772000, "state": "OPEN", "openedAt": 1788311428000, "closedAt": null, "settlePrice": null, "pnl": null,
  "mark": "65612.0", "markFresh": true, "distanceAbs": "2612.0", "distancePct": "3.98", "distanceToTpAbs": "888.0", "distanceToTpPct": "1.35",
  "unrealizedPnl": "140.500000", "requirement": "2083.850000", "maxLoss": "2224.350000", "premium": "2224.350000", "potentialProfit": "1028.500000", "leverage": "26.49",
  "commission": "22.243500", "closeCommission": null, "estimatedCloseCommission": "22.243500", "notional": "65612.000000", "venueRfqId": 5207, "rfqId": 311, "closeReason": null, "closeRfqId": null,
  "strictTakeProfit": false, "premiumBps": 9000, "currency": "USDC"
}

Terminal states: KNOCKED_OUT (at the barrier), TAKE_PROFIT (at the take profit), EXPIRED, EARLY_CLOSE (closed by an accepted close request at the quoted price), TORN_UP (a venue liquidation tear-up), CLOSED (any other termination), with settlePrice, pnl and closeReason (knockOut, takeProfit, expiry, earlyClose, liquidation, finalSettlement). Since revision 10 (BROKER-14) every row carries closeCommission (our early-close commission, set on an EARLY_CLOSE row, 0.000000 on every other terminal row, null while the contract is open) and an OPEN row estimatedCloseCommission (the early-close commission reserved beside the requirement, estimated at the entry; null on a terminal row); commission is the opening commission, basis points of the premium at the client's BARRIER scheme with the per-contract minimum (OQ-36 D16).

POST /clients/{clientId}/barriers/{contractId}/close (TRADE, Idempotency-Key), body {autoAccept?, expiresInMs?} (both optional): a close request to the contract's writer; quotes are acceptable strictly inside the contract's terms; the accept settles the contract EARLY_CLOSE at the quoted price. Since revision 10 (BROKER-14, the operator's decision of 2026-09-09 on OQ-43) the accept of a close request charges our EARLY-CLOSE COMMISSION: the client's BARRIER scheme applied to the premium at the accepted close price (the same rate and per-contract minimum as the entry; the close request's commission, the accept answer's closeCommission, the contract's closeCommission, one COMMISSION settlement item with refs {contractId, symbol, reason: "earlyClose", closeTradeId} dated at the close), reserved while the contract is open as estimatedCloseCommission; a knock-out, take profit, expiry or venue close carries no commission. Answer: the close request as an <rfq> with closeContractId and contractEntry set. 400 code 4000 when the contract is not open or a close request is already open (data.rfqId names it), 404 code 4004 for a foreign contract. Since revision 12 (the venue's ADR-25): the venue values a close request and the writer's close quote at the contract's WHOLE quantity against the market's minNotional, so a contract worth less than the minimum at the current mark cannot be closed early and ends at its barrier, its take profit or its expiry; such a close request ends REJECTED with "This contract is worth less than the market minimum (100.00 USD) at the current mark; it ends at its barrier, its take profit or its expiry." as rejectReason (400 code 4000 with data {rfqId, state: "REJECTED"}, the rfq.rejected webhook); we run no check of our own on a close, so the sentence disappears by itself should the venue exempt closes from the floor; termination and settlement are never floored.

12.3 Perpetual and spot markets: margin, leverage, orders, positions

The margin picture, the pre-trade preview and the per-market leverage choice are the same bodies as our client API's GET /v1/margin, POST /v1/margin/preview and GET | PUT /v1/leverage, so a partner reads exactly what its client would see in our portal. Money figures are USDC strings with 6 places.

GET /clients/{clientId}/margin: (bare) the live margin picture:

{
  "clientId": 412, "equity": "10009.800000", "cash": "10000.000000", "unrealizedPnl": "9.800000", "reserved": "0.000000",
  "initialMargin": "120.000000", "maintenanceMargin": "60.000000", "marginCallLevel": "120.000000", "positionMargin": "120.000000", "orderMargin": "0.000000",
  "freeMargin": "9889.800000", "marginLevel": "8341.50", "riskState": "NORMAL", "categorization": "RETAIL", "marksFresh": true,
  "closeOutPct": "50", "marginCallPct": "100",
  "positions": [
    {"symbol": "BTC-USD-PERP", "netQty": "0.01", "avgEntryPrice": "60000", "mark": "60980", "markFresh": true, "unrealizedPnl": "9.800000",
     "initialMargin": "120.000000", "roiPct": "8.17", "leverage": 5, "realizedPnl": "0.000000", "estLiquidationPrice": null}
  ],
  "openOrders": 0,
  "barrierMargin": "0.000000", "barrierUnrealizedPnl": "0.000000", "barrierMarksFresh": true, "pendingAcceptMargin": "0.000000", "closeOutEquity": "10009.800000",
  "barriers": []
}

riskState is NORMAL, MARGIN_CALL or CLOSE_OUT; marginLevel is the equity as a percentage of the total initial margin (barrier requirements included; null without margin), marginCallPct and closeOutPct the percentages of the PERPETUAL margin (positionMargin + orderMargin) at which the account enters margin call and close-out (100 and 50 by default: the close-out at half the margin required is the regulatory margin close-out), each the value that applies to this client, never below the brokerage value (a partner may agree a tighter level for its clients with us; it is set by our back office, never on this API), maintenanceMargin the close-out level in money and marginCallLevel (additive, revision 10) the margin call level in money, (positionMargin + orderMargin) x marginCallPct / 100, the same figure the margin.call event carries, so a partner never derives it; the two are compared against closeOutEquity (docs/13 section 2.5). A position's initialMargin (and so positionMargin) is |netQty| x max(mark, avgEntryPrice) / leverage on a leveraged position since 11 September 2026 (revision 10 grown in place, values only): never below the margin required to open it, rising with the mark as before, so a losing long is held at its opening margin and a winning short no longer frees margin as the mark falls; roiPct and estLiquidationPrice follow (docs/13 2.2 and 2.6). A fully funded position (leverage 1) keeps |netQty| x mark. closeOutEquity is the conservative equity our close-out test compares (open barrier profits excluded); barriers lists the open barrier contracts in the shape of section 12.2 (each with estimatedCloseCommission, revision 10) and barrierMargin their requirement plus the reserved early-close commissions (inside initialMargin). Under PARTNER custody cash is the collateral the partner reported, less what the client has lost and paid since, exactly as our ledger holds it. 503 code 5030 when the margin service is not attached. The transitions of riskState reach your webhook as margin.call, margin.call_cleared, margin.close_out_started and margin.close_out_done, each with the figures of this read at the transition (section 16.4); this read stays the source of the live numbers between events and the fallback when a delivery failed for good.

The written specification of the risk engine behind these figures (the arithmetic, the parameters, the state machine, the cadence and latency, the close-out algorithm, stale marks, negative balance protection and what the partner sees at each step) is docs/13-risk-engine-for-partners.md.

POST /clients/{clientId}/margin/preview: (bare) the pre-trade check of an order, nothing written. Body {symbol, side, type, tif?, qty, price?, trigger?, reduceOnly?, leverage?} (the order shape of the orders route below; leverage previews at that leverage instead of the stored choice and is not persisted):

{
  "accepted": true, "reason": null, "reservation": null, "orderValue": "600.000000", "marginRequired": "120.000000", "leverage": 5,
  "freeMarginBefore": "10000.000000", "freeMarginAfter": "9880.000000", "marginLevelAfter": null, "estLiquidationPrice": null,
  "equityBefore": "10000.000000", "initialMarginBefore": "0.000000", "initialMarginAfter": "120.000000",
  "estimatedCommission": "0.300000", "slippageAllowance": "0.000000", "estimatedCosts": "0.300000"
}

accepted: false carries the refusal sentence in reason, the same sentence the orders route would answer (since revision 26 also the conditional limit band below, with the after figures null). A malformed shape answers 400 code 4000 with accepted: false; a market that is not offered 404 code 4004. On a spot market reservation names what the order would reserve.

GET /clients/{clientId}/leverage?symbol: (bare) the client's leverage on one perpetual market, {symbol, leverage, cap, categorization, chosen}: cap is the schedule's maximum for the client's categorisation on the environment you are connected to; read it from this route (on the development environment today RETAIL 10x on the crypto perpetuals, 20x on the index, metal and energy perpetuals, 30x on the FX perpetuals, PROFESSIONAL 50x; production publishes its figures at go-live), chosen the client's stored choice (null until one is set) and leverage the effective figure (the choice, else the cap). 400 code 4000 without symbol, 404 code 4004 for a market that is not offered.

PUT /clients/{clientId}/leverage (TRADE, Idempotency-Key; POST is accepted with the same body), body {symbol, leverage, force?}: stores the choice and answers the same view. 400 code 4000 above the cap or not a whole number; 404 code 4004 for a market that is not offered; 409 code 4090 when the change would need more initial margin than the account holds (data: {wouldBreach: true, initialMarginAfter, maintenanceMarginAfter, freeMarginAfter, marginLevelAfter, riskStateAfter}; repeat with force: true to apply it anyway). The stored leverage is what the orders route margins at; an order carrying a leverage hint that no longer matches the stored choice answers 409 code 4091. While your server-side order entry is CLOSED (22.10) this route, POST .../orders and DELETE .../orders/{orderId} answer 403 code 4043 SERVER_ORDER_ENTRY_CLOSED (revision 21), and the same changes come from your app's order commands (section 22).

POST /clients/{clientId}/orders (TRADE, Idempotency-Key), body PlaceOrderRequest:

Answer (bare) {orderId, clOrdId, state} on acceptance ({"orderId": 4182, "clOrdId": "BARR-4182", "state": "ACKED"}; state SENT when the venue's acknowledgement was lost in transport or could not be recorded on our side, or, since revision 23, the venue answered that it could not confirm the order: the order may be live, read it back, and the key replays this answer, section 5); 400 {code: 4000, msg, error, orderId, clOrdId, state} on a refusal (orderId null when nothing was written); 403 code 4030 on the verification gate; 403 code 4041 PARTNER_CLOSE_ONLY on an opening order while your clients are close-only under the settlement tier (15.7; the same bare fields with orderId null and data: {error: "PARTNER_CLOSE_ONLY"}; a reduce-only order and an order within the reduce capacity pass); 409 code 4091 {leverageSent, leverageStored}.

THE CONDITIONAL LIMIT BAND (revision 26). The venue checks a plain LIMIT price against the market's price band but checks neither the trigger nor the limit of a conditional order, so a triggered limit order could rest or trade far from the market, or sweep the book past the venue's market-order protection. We therefore refuse, before anything is written and before the venue, a STOP_LIMIT or TAKE_PROFIT_LIMIT whose trigger.limitPrice lies outside the market's band (priceBandBps on GET /market-info, 10 percent on the crypto perpetuals today; a market that publishes none has no band) around the price at which the order becomes a limit order: its trigger.price, or the current mark when the mark has already reached the trigger (AT_OR_ABOVE: the mark at or above it; AT_OR_BELOW: at or below it). The band is floor(reference x priceBandBps / 10000) in whole price steps, both bounds inside. 400 code 4000 with orderId null and the sentence, for example "The limit price 1 is outside the price band of this market: this order becomes a limit order at its trigger price 64000, so its limit price must lie within 10 percent of the trigger price, from 57600 to 70400." (with the mark: "The limit price 96000 is outside the price band of this market: the mark price 60000 has already reached this order's trigger price, so its limit price must lie within 10 percent of the mark, from 54000 to 66000."). The trigger price itself is not bounded: a stop loss or take profit far from the market with its limit near its trigger is accepted. Reduce-only orders are checked too, and on a market that publishes a band a conditional limit order, reduce-only or not, needs a fresh mark ("There is no fresh mark price for BTC-USD-PERP right now. Please try again shortly."; a STOP_MARKET or TAKE_PROFIT_MARKET reduce-only order does not, so a position can always be protected); while the venue's instrument list cannot be read it is refused with "This market's specification is unavailable right now. Please try again shortly.". An attach leg with a limitPrice is checked against the band around its own price when the parent order is placed ("The stop loss limit price 1 is outside the price band of this market: it must lie within 10 percent of its trigger price 55000, from 49500 to 60500."); the legs we place once the parent filled are never refused by it. Derive a conditional limit from its trigger and the market's priceBandBps at run time, never as a fixed offset from today's price. The preview answers the same sentence as accepted: false.

Spot markets are prefunded: a BUY reserves the worst-case quote cash plus commission, a SELL the asset; they refuse reduceOnly, attach, ocoGroup and market-type conditional buys. The order's life reaches your webhook as order.accepted, order.partially_filled, order.filled, order.canceled and order.rejected, each carrying the order in the shape below plus the fill (section 16.4).

DELETE /clients/{clientId}/orders/{orderId} (TRADE): (bare) {orderId, clOrdId}; 404 code 4004 for a foreign order, 400 code 4000 when the order is terminal or the venue refused; 502 code 5020 when the venue could not be reached and, since revision 23, when the venue could not confirm the cancel (the sentence of section 12, the order unchanged until the venue's confirmation arrives; a cancel may be sent again at once).

GET /clients/{clientId}/orders/open: {code: 0, data: [<order>]}. GET /clients/{clientId}/orders?limit&before: (bare) {orders, hasMore, nextBefore}, limit 1 to 500. An order:

{
  "orderId": 4185, "clOrdId": "BARR-4185", "symbol": "BTC-USD-PERP", "family": "PERP", "side": "BUY", "type": "LIMIT", "qty": "0.5", "price": "64250.0",
  "state": "FILLED", "reject": null, "filledQty": "0.5", "createdAt": 1788311500000, "reduceOnly": false, "tif": "GTC", "trigger": null, "updatedAt": 1788311600120,
  "attach": {"takeProfit": {"price": "66000.0"}, "stopLoss": {"price": "62800.0"}, "legs": [4186, 4187]},
  "ocoGroup": null, "parentOrderId": null, "parentClOrdId": null, "origin": "CLIENT", "note": null, "replacedBy": null, "replaces": null, "reservation": null,
  "channel": "REST", "channelKeyId": null, "channelRef": null
}

channel, channelKeyId and channelRef (additive, revision 9): the transport that placed the order, REST for every order of these routes and FIX for an order entered on a FIX session (section 20), with the key of that session (the keyId of GET /me) and the ClOrdID(11) the session sent; since revision 21 APP for an order your app placed directly with an app order command (section 22: the place, and the new order of a replace), with channelKeyId null and channelRef the jti of the token that carried the command, our record of it (22.11; it is never a reference of yours, and over FIX such an order carries no ClOrdID(11)); the take profit and stop loss legs of an attached order read APP with channelRef null; REST with two nulls otherwise. An app order's origin is CLIENT, like every order the client instructs. A flatten of our risk engine reads origin: "CLOSE_OUT" with channel: "REST"; so does the forced sale of a client's spot holdings after a close-out left its cash negative (docs/13 section 8): a SELL, MARKET, IOC order on the spot market in the client's name with origin: "CLOSE_OUT" and family: "SPOT", reduceOnly false, prefunded in the asset like any spot sale and settled by its fill like one; it runs for a client only once that client has accepted the Terms version carrying the right-of-sale clause, our configuration naming that version and the sale never running while it names none (revision 10).

GET /clients/{clientId}/positions: (bare) {positions: [{symbol, netQty, avgEntryPrice, netCost, realizedPnl, updatedAt}]}. GET /clients/{clientId}/trades?limit&before: (bare) {trades: [{id, venueTradeId, orderId, clOrdId, symbol, family, side, price, qty, commission, ts, realizedPnl, notional, asset}], hasMore, nextBefore}. GET /clients/{clientId}/position-history?limit&before: (bare) {items: [{id, orderId, clOrdId, symbol, side, qty, price, realizedPnl, ts}], hasMore, nextBefore} (the fills that realised P&L).

Worked example: a perpetual round trip

The sequence our tests pin for a PARTNER-custody client at level MICA_MIFID with 10000 USDC of reported collateral (section 15.1) and the mark of BTC-USD-PERP at 60000:

1. GET .../leverage?symbol=BTC-USD-PERP answers {"symbol": "BTC-USD-PERP", "leverage": 10, "cap": 10, "categorization": "RETAIL", "chosen": null}.
2. PUT .../leverage {"symbol": "BTC-USD-PERP", "leverage": 5} answers {"symbol": "BTC-USD-PERP", "leverage": 5, "cap": 10, "categorization": "RETAIL", "chosen": 5}; {"leverage": 50} answers 400 code 4000 (above the cap).
3. POST .../margin/preview {"symbol": "BTC-USD-PERP", "side": "BUY", "type": "LIMIT", "qty": "0.01", "price": "60000"} answers accepted: true, leverage: 5, marginRequired: "120.000000" (600 of notional at 5x), freeMarginBefore: "10000.000000".
4. POST .../orders with the same body answers {"orderId": 4185, "clOrdId": "BARR-4185", "state": "ACKED"}; GET .../orders/open lists it; DELETE .../orders/4185 answers {"orderId": 4185, "clOrdId": "BARR-4185"} and the order leaves the open list once the venue acknowledges the cancel (state PENDING_CANCEL until then).
5. POST .../orders {"symbol": "BTC-USD-PERP", "side": "BUY", "type": "MARKET", "qty": "0.01"} fills at 60000: GET .../positions shows {"symbol": "BTC-USD-PERP", "netQty": "0.01", "avgEntryPrice": "60000", ...} and GET .../margin carries the position with its initialMargin of 120.
6. The mark moves to 61000. POST .../orders {"symbol": "BTC-USD-PERP", "side": "SELL", "type": "MARKET", "qty": "0.01", "reduceOnly": true} fills at 61000: the position is flat, GET .../trades lists both fills with realizedPnl "10.000000" on the closing one, and, under PARTNER custody, exactly one settlement item of type PNL for +10.000000 plus one COMMISSION item per fill appear on GET /partner/v1/settlement/items (section 15.3).

Every write of the sequence is attributed on the client's audit stream ("order placed for client BARR-00000412 by partner NEOBROKER1 key pbk_1f9c2d..."). Before MICA_MIFID, step 4 answers 403 code 4030 with missingBlocks naming the MiFID blocks and nothing is written; the barrier lifecycle of section 12.2 (preview, request, quote, accept, knock-out) runs through the same gate and the same collateral.

12.4 Staking swaps

Writer-first swap markets: a writer posts an offer (rate, tenor, size); the client takes a size, the principal leaves the account at the take and comes back with the reward at maturity, paid by the writer. The writer's obligation is UNSECURED (the disclosure on every answer must be shown to the client); a writer who fails to pay leaves a claim (swap.defaulted).

GET /staking/markets: {markets: [{symbol, name, asset, venueAsset, enabled, minTenorDays, maxTenorDays, maxRateBps, maxRatePct, minQty, qtyStep, maxQty, takerFeeRate, displayDecimals, commissionRewardBps, family, usualTenors}], disclosure, commissionRewardBps}. name is the product name of the market (USD, EUR, BTC, ETH, SOL and USD1 Fixed Yield Contract since revision 10; the same name rides on the offer rows, the swap records and the take answer). takerFeeRate is the broker's effective venue taker rate on the market (the venue's listed rate, or the member's measured tier or programme rate): the rate a take reserves for and the fee leg is posted at, so a preview computed from it matches the charge. usualTenors (revision 10) is the list of terms writers usually offer on the market, in whole days ascending, always present and [] when the market lists none; it is a presentation hint (a writer may offer any term inside minTenorDays to maxTenorDays).

GET /staking/offers?asset&symbol: {offers: [{offerId, symbol, name, asset, venueAsset, rateBps, ratePct, tenorDays, qty, remainingQty, minQty, expiryTs, createdTs, rewardPerUnit, commissionRewardBps, offered}], asOf, stale, disclosure, commissionRewardBps}. The board is polled from the venue every 2 s and cached 3 s. offered (revision 10, BROKER-84) is false while our operator disabled the offer's market: the offer stays listed, a take of it answers 400 code 4000 with "This market is not currently offered.", and GET /staking/markets omits the market meanwhile.

POST /clients/{clientId}/staking/{offerId}/accept (TRADE, Idempotency-Key), body {qty} (in the market's asset, on the lot grid): the gates, the reservation in the asset, the venue take, the principal legs. Answer {code: 0, data: <swap>}:

{
  "code": 0,
  "data": {
    "swapId": 88, "contractId": 412, "tradeId": 771412, "offerId": 6103, "symbol": "USD-TBILL-SWAP", "name": "USD Fixed Yield Contract", "asset": "USDC", "venueAsset": "USD", "displayDecimals": 2,
    "qty": "10000", "notional": "10000.00", "rateBps": 450, "ratePct": "4.50", "tenorDays": 91, "reward": "112.19", "fee": "2.00", "expectedPayout": "10112.19",
    "state": "OPEN", "openedTs": 1788311700000, "maturityTs": 1796174100000, "closedTs": null,
    "paid": "0.00", "outstanding": "0.00", "claim": "0.00", "writtenOff": "0.00", "recovered": "0.00",
    "commission": "0.00", "commissionRewardBps": "1000", "estimatedCommission": "11.22", "settleReason": null, "rejectReason": null, "ts": 1788311700000, "createdAt": 1788311700000
  }
}

The broker commission is a share of the reward (commissionRewardBps), frozen at the take and charged at the close. Errors: 400 code 4000 (size rules, a disabled market, the balance short of notional plus fee), 403 code 4030, 403 code 4041 PARTNER_CLOSE_ONLY (a take while your clients are close-only under the settlement tier, 15.7), 404 code 4004 (the offer left the board), 502 code 5020 (the row stays ACCEPTING, the poll resolves it).

GET /clients/{clientId}/staking/swaps?state&limit&before (state live default, history, all): {swaps, hasMore, nextBefore}. GET /clients/{clientId}/staking/swaps/{swapId}: one swap by the venue contract id (the router's swap id is accepted when no contract of the client carries that id). Swap states: ACCEPTING (the take is at the venue), OPEN, MATURED (paid in full at maturity), DEFAULTED (the writer was short at maturity; claim is what the client can still expect, later payments cure it), CURED (a defaulted swap paid in full later), FINAL_SETTLEMENT (the market was delisted and the venue settled the contract), REJECTED; settleReason matured, default, cured, finalSettlement.

12.5 Account reads

The reads of this section name the client by the route alone and do not repeat its identifiers. Of the answers that do name the client, the margin read of 12.3 (GET /clients/{clientId}/margin) and the statement rows of section 17 carry clientId only, without clientUid or partnerClientRef (revision 25, section 7): key them by clientId.

GET /clients/{clientId}/balances: (bare) {balances: [<row>], portfolioValue, portfolioCurrency, portfolio}, one row per currency, the USDC cash row first with the margin figures:

{
  "balances": [
    {"currency": "USDC", "kind": "CASH", "cash": "9800.000000", "reserved": "125.000000", "total": "9925.000000", "free": "9800.000000", "displayDecimals": 2, "venueAsset": "USD",
     "equity": "10250.410000", "unrealizedPnl": "450.410000", "freeMargin": "9100.250000", "mark": null, "markFresh": null, "value": "9925.000000", "valueCurrency": "USDC",
     "staked": "1000.000000", "swapClaims": "0.000000", "stakedValue": "1000.000000", "claimsValue": "0.000000", "valuationBasis": "CASH"},
    {"currency": "BTC", "kind": "ASSET", "cash": "0.05000000", "reserved": "0.00000000", "total": "0.05000000", "free": "0.05000000", "displayDecimals": 8, "venueAsset": "BTC",
     "equity": null, "unrealizedPnl": null, "freeMargin": null, "mark": "65000", "markFresh": true, "value": "3250.000000", "valueCurrency": "USDC",
     "staked": "0.00000000", "swapClaims": "0.00000000", "stakedValue": null, "claimsValue": null, "valuationBasis": "MARK"}
  ],
  "portfolioValue": "14500.410000", "portfolioCurrency": "USDC",
  "portfolio": {"cashTotal": "9925.000000", "reserved": "125.000000", "withdrawalHolds": "0.000000", "holdingsValue": "3250.000000", "stakedValue": "1000.000000", "unrealizedPnl": "450.410000", "claimsValue": "0.000000", "holdingsValued": true, "currency": "USDC", "valuationBasis": "MARK"}
}

Every row carries valuationBasis (revision 10): CASH on the cash row, MARK on an asset valued at the spot or perpetual mark, PAR on a currency our registry values at 1.000000 USDC per unit without a market price (mark null, markFresh true, value, stakedValue and claimsValue at par; such a value may not be realisable), NONE on an asset without a mark (counted zero); the portfolio block and the overview root carry the aggregate over the non-cash rows (MARK, PAR or MIXED). The staked principal is at full value and unsecured (out with writers, at risk): the principal STILL out with writers, so a partial return already in the client's cash is not counted twice (since 2026-09-12, the code audit of 2026-09-11, B-472; a value rule, the staked and stakedValue members unchanged in shape); the claims are apart (owed, not paid); no currency is PAR yet. portfolioValue is the ONE figure of GET .../account/overview and the equity history: the margin equity (USDC cash and reserved plus the unrealised P&L) plus the valued holdings plus the staked principal (revision 11: computed from the same margin snapshot on both routes; before, this route summed the USDC total, so a pending USDC withdrawal request stayed inside it while the overview kept it out). A pending USDC withdrawal's reservation (a REQUESTED request, the amount held in reserved) is outside portfolioValue on both routes and outside equity; it returns to the figure when the request is rejected or released and leaves the account when it is approved. The portfolio block carries it additively as withdrawalHolds (revision 11), so that cashTotal - withdrawalHolds + holdingsValue + stakedValue + unrealizedPnl = portfolioValue and cashTotal keeps meaning the USDC row's total.

GET /clients/{clientId}/account/summary: {code: 0, data: {currency, realizedPnl, commissionPaid, fundingPaid, tradeCount, since, sinceTs, realizedTotal, realizedByFamily: {fills, spot, barrier, staking}, commissionByFamily: {fills, barrier, staking}, counts: {fills, barrierContracts, swapTakes}}} (lifetime figures).

GET /clients/{clientId}/account/overview: {code: 0, data: {...}}, the whole portfolio in one round trip: equity, cash, free margin, initial margin, unrealised P&L, holdings with FIFO cost, staked rows, realised and commission figures per family, counts, wins and losses, the allocation, the verification level (503 code 5030 without the margin engine).

GET /clients/{clientId}/ledger?limit&before: {code: 0, data: {postings: [{postingId, txId, type, actor, reason, ts, amount, currency, kind, refs}], hasMore, nextBefore}}, limit 1 to 500 (default 100), newest first. kind is the account (cash, reserved), type the transaction type (DEPOSIT, WITHDRAWAL_RESERVE, WITHDRAWAL, WITHDRAWAL_RELEASE, COMMISSION, PNL, FUNDING, BARRIER_SETTLE, SWAP_PRINCIPAL, SWAP_SETTLE, SWAP_FEE_ADJUST, PARTNER_COLLATERAL_IN, PARTNER_COLLATERAL_OUT, ...; every commission, a fill's, a barrier entry's or our share of a staking swap's reward, is a COMMISSION posting whose refs say which, revision 6; a FUNDING posting carries the refs of a funding item, 15.3, with fundingRate, markPrice and roundingRemainder since revision 24), actor partner:<CODE> on the partner's own postings (deposits, withdrawals and collateral reports).

GET /clients/{clientId}/notifications?since: the client's notification items newer than since (Unix ms, default the last 24 hours), oldest first, at most 200: {code: 0, data: {items: [{kind, ref, ts, event}], since, asOf}}. event is the partner webhook event name the kind maps to (section 16.4), null for kinds that are not forwarded. Poll this when you prefer pulling over webhooks.

13. Custody models

Every partner is configured by our operations team with one of two custody models. The model decides who holds the clients' money, which money routes the partner uses, and how the economic results of trading are settled between the partner and us. GET /partner/v1/me carries custodyModel and collateralAsset; the model is set and changed by our operations team with a recorded reason, never by the partner.

What does NOT change with the model: the reliance onboarding, the MiFID assessment, the verification gates on money movements (level MICA and the enhanced due diligence source-of-wealth ask, which is the SOURCE_OF_WEALTH block of PUT .../mifid and whose deposit sum counts collateral deposits like any other deposit; the rule is in 15.1), the client restrictions, the trading routes, the statements (their content follows the model in one place: the quarterly CLIENT_ASSETS statement's balances and MiCA notes describe a PARTNER custody client's USDC balance as the mirror of the collateral you hold, section 17), and the fact that OUR ledger is the record of the client's balance with us at all times.

On our books a PARTNER-custody partner has one distinct house account, partner_custody:<partnerId>, whose balance is minus the collateral the partner holds for our clients; collateralHeld in the settlement summary is that figure. Every interfirm payment our finance records moves that account by the amount paid (positive = we paid the partner) against a second house account partner_interfirm:<partnerId>, the firm's own receivable or payable with the partner, so collateralHeld is the booked collateral reports plus the interfirm payments recorded, and the aggregate collateral the partner holds for our clients equals collateralHeld plus the outstanding interfirm balance over the whole history (revision 10). A BROKER-custody partner's client cash sits against our transit house account instead.

Changing the custody model (revision 4). The model is changed by our operations team only, and only on a partner with nothing standing under the old model: the change is refused while any of the partner's clients holds a nonzero USDC cash or reserved balance, while our house account partner_custody:<partnerId> is nonzero, while a settlement item is PENDING or FAILED, while a deposit notice is PENDING, while a withdrawal request is REQUESTED or APPROVED, or while your clients are close-only under the settlement escalation of 15.7 (the operator sees the standing items named; the close-only state lifts on our next hourly check after every item is settled and reported and the unsettled sum is under the cap, so that last condition holds for at most an hour once the others are met). Because a client with money at us blocks the change, the unwind happens with every client of the partner flat and paid out. Unwinding a PARTNER model: settle and report every settlement item, agree and pay the interfirm balance (recorded by our finance; the record moves partner_custody:<partnerId> by the payment, so once every client's collateral is reported withdrawn the account reads zero), report every client's collateral as withdrawn (direction: WITHDRAWAL down to a zero balance); then the model changes and, under BROKER, the clients are funded again through deposit notices. Unwinding a BROKER model: let finance decide every pending notice, approve and pay or reject every open withdrawal request, pay every client out (withdrawal requests down to a zero balance); then the model changes and, under PARTNER, the partner reports the collateral it holds. The trading routes are not touched by the change; the settlement items and collateral reports already on file stay readable.

14. Money under BROKER custody

Partner clients fund their accounts THROUGH THE PARTNER: the partner receives the client's money (fiat or crypto) on its own rails, notifies us of the deposit, and our finance team confirms it against the settlement between the partner and us; withdrawals are requested by the partner, paid out by the partner to the client, and confirmed as paid by our finance team. Our ledger is the record of the client's balance at all times; the partner and our finance reconcile through the settlement report. A PARTNER-custody partner uses section 15 instead of 14.1 and 14.2 (the two routes answer 409 code 4092 for it) and reads the settlement report of 14.3 with its interfirm block.

Both money writes pass the client's verification gate for a crypto movement (DEPOSIT:CRYPTO / WITHDRAW:CRYPTO: level MICA, and the enhanced due diligence source-of-wealth ask once cumulative deposits reach the threshold; 403 code 4030 with missingBlocks), the account state (a closed account 409 code 4092) and the client's money restrictions (409 code 4092). The ask is the SOURCE_OF_WEALTH block of PUT .../mifid; its rule is stated once, in 15.1, and its threshold, its sum and its cure are the same under both custody models: here the deposits counted are the deposit notices our finance confirmed (a notice in a currency other than USDC counts at the USDC value recorded for it at the confirmation, and at zero when none was recorded), and the ask is met when the next notice or withdrawal request is filed. The retry note at the end of 15.1 does not apply here: a partnerRef you already filed replays before the gate (section 5), so a retry answers the original notice or request.

14.1 Deposit notices

POST /clients/{clientId}/deposits (TRADE, Idempotency-Key):

Answer 201 with the notice:

{
  "code": 0,
  "data": {"noticeId": 77, "partnerId": 7, "clientId": 412, "clientUid": "BARR-00000412", "partnerRef": "dep-2026-0001", "currency": "USDC", "amount": "1500.000000", "method": "FIAT", "evidenceRef": "SEPA-9F3A", "status": "PENDING", "createdAt": 1788312000000, "decidedBy": null, "decidedAt": null, "decisionNote": "", "ledgerTxId": null}
}

Deposit state machine:

PENDING --confirm (finance)--> CONFIRMED   ledger DEPOSIT: client cash + amount, house transit; webhook deposit.confirmed
PENDING --reject (finance)---> REJECTED    no posting; webhook deposit.rejected

A sandbox partner's notice is confirmed inside the POST (the 201 already says CONFIRMED with the ledgerTxId). The confirmation is idempotent on our side (ledger key partnerdep:{noticeId}), so a notice is never credited twice. decidedBy on a notice (and on a withdrawal request, section 14.2) is the decider's ROLE label (FINANCE, ADMIN; PARTNER on a sandbox partner's instant decision), never a person's name (revision 6).

GET /clients/{clientId}/deposits?status&limit&before and GET /partner/v1/deposits?status&limit&before (partner-wide): {deposits, hasMore, nextBefore}, status one of PENDING, CONFIRMED, REJECTED, limit 1 to 200 (default 50).

14.2 Withdrawal requests

POST /clients/{clientId}/withdrawals (TRADE, Idempotency-Key):

The free balance is checked under the client's lock inside the request's own transaction (revision 4), so nothing that moves the client's money or margin can slip in between the check and the reserve: the cash (400 code 4000 "Insufficient free balance for this withdrawal."), and for USDC the lesser of the cash and the free margin, never in a margin call or close-out, whether recorded on the account or implied by the live marks (400 code 4000 "This withdrawal would leave the account short of margin for its open positions."). The amount is reserved at once (cash to reserved, WITHDRAWAL_RESERVE); the reserve is on its way out, so it neither shields open positions nor counts as margin (the client's equity and free margin read as if it had already left). Answer 201 with the request:

{
  "code": 0,
  "data": {"requestId": 41, "partnerId": 7, "clientId": 412, "clientUid": "BARR-00000412", "partnerRef": "wd-2026-0001", "currency": "USDC", "amount": "500.000000", "destination": {"iban": "DE89370400440532013000", "reference": "wd-2026-0001"}, "status": "REQUESTED", "createdAt": 1788312100000, "decidedBy": null, "decidedAt": null, "paidAt": null, "decisionNote": "", "ledgerTxId": 9911}
}

Withdrawal state machine:

REQUESTED --approve (finance)--> APPROVED --pay (finance)--> PAID
   |  ledger WITHDRAWAL: reserved to house transit        (paidAt set; the partner has paid the client)
   |
   +--reject (finance)-----------> REJECTED   ledger WITHDRAWAL_RELEASE: reserved back to cash
   +--cancel (partner)-----------> CANCELLED  ledger WITHDRAWAL_RELEASE

Every transition fires withdrawal.status. A sandbox partner's request is approved and paid inside the POST (the 201 says PAID).

Finance's approval re-runs the money-out gate under the client's lock (revision 4): a client restriction, an open reconciliation break that pauses money out in that currency, or in every currency for a ledger-proof break, a margin call or close-out (recorded or implied by the live marks), or free funds that no longer cover the amount refuse the approval and leave the request REQUESTED with its reserve; finance then approves later or rejects it (the release). Nothing changes on the wire for you: the request stays REQUESTED until a transition fires withdrawal.status.

POST /clients/{clientId}/withdrawals/{rid}/cancel (TRADE, Idempotency-Key): the partner's own cancel while REQUESTED; {request, alreadyDecided}; 409 code 4092 once approved.

GET /clients/{clientId}/withdrawals?status&limit&before and GET /partner/v1/withdrawals?status&limit&before: {withdrawals, hasMore, nextBefore}, status one of REQUESTED, APPROVED, PAID, REJECTED, CANCELLED.

14.3 Settlement report (both custody models)

GET /partner/v1/settlement?from&to (Unix ms; default the whole history up to now): per currency the confirmed deposits and paid withdrawals of the window (by decision and payout time), the commissions charged to the partner's clients and their realised results (the ledger postings of the window), and the closing client cash (cash plus reserved of every partner client) as of to. This is the reconciliation the partner and our finance agree on.

{
  "code": 0,
  "data": {
    "from": 1785715200000, "to": 1788307200000, "asOf": 1788312200000, "custodyModel": "BROKER", "collateralAsset": "",
    "currencies": [
      {"currency": "USDC", "depositsConfirmed": "250000.000000", "withdrawalsPaid": "61200.000000", "commissions": "1840.250000", "realizedPnl": "-3120.400000", "closingClientCash": "186710.500000"}
    ],
    "interfirm": null,
    "definitions": {"commissions": ["COMMISSION"], "realizedPnl": ["PNL", "BARRIER_SETTLE", "SWAP_SETTLE", "FUNDING"], "closingClientCash": "client cash plus reserved of the partner's clients as of `to`", "interfirm": "only a PARTNER-custody partner carries the interfirm block"}
  }
}

commissions is positive for a charge; every commission (a fill's, a barrier entry's, our share of a staking swap's reward) is a COMMISSION posting (revision 6 dropped SWAP_COMMISSION and BARRIER_COMMISSION from the list: they were documented and never posted). realizedPnl is signed from the client's point of view.

For a PARTNER-custody partner custodyModel is PARTNER, depositsConfirmed and withdrawalsPaid stay zero (collateral reports are not finance-desk deposits), and interfirm is the block of section 15.5 for the same window, {currencies: [{currency, owedToPartner, owedByPartner, net, settlementsRecorded, outstanding}], definitions}, with definitions.interfirm "the settlement items of the window from our view, less the interfirm settlements recorded whose period overlaps it".

15. Collateral and settlement under PARTNER custody

Under PARTNER custody the partner is the custodian. Three things replace the deposit notices and withdrawal requests:

1. Collateral reports (15.1, 15.2): the partner tells us, per client, every movement of the stablecoin collateral it holds for the client. We book each report at once, 1:1 in USDC, and the booked figure is the cash the risk engine margins.
2. Settlement items (15.3, 15.4): every economic event on such a client on our side (a realised profit or loss, a commission, a funding payment, a barrier settlement, a swap flow, a manual correction) becomes exactly one settlement item, and a posting our reconciliation restates later (for example a funding charge, 15.3, revision 22) becomes a further item of its own. The partner credits or debits its client's stablecoin accordingly and reports each item back as SETTLED or FAILED.
3. The interfirm balance (15.5, 15.6): the net of all settlement items is what we owe the partner or the partner owes us; our finance records the interfirm payments and both sides see the outstanding balance.

15.1 POST /clients/{clientId}/collateral

Scope TRADE, Idempotency-Key recommended. Reports one collateral movement:

A DEPOSIT is booked as the ledger transaction PARTNER_COLLATERAL_IN: the client's USDC cash plus amount against our house account partner_custody:<partnerId>, actor partner:<CODE>, ledger key pcol:<reportId>, refs {partnerId, reportId, partnerRef, sourceAsset, txRef, direction, occurredAt}. A WITHDRAWAL is PARTNER_COLLATERAL_OUT the other way. Neither produces a settlement item: the report is the partner's own movement, not an economic event. The enhanced due diligence deposit sum counts collateral deposits like any other deposit (the rule is stated below, after the refusal rules).

Answer 201:

{
  "code": 0,
  "data": {
    "reportId": 501, "status": "BOOKED", "ledgerTxId": 10231,
    "balances": {"cash": "10000.000000", "reserved": "0.000000", "free": "10000.000000", "freeMargin": "10000.000000"},
    "report": {
      "reportId": 501, "partnerId": 7, "clientId": 412, "clientUid": "BARR-00000412", "partnerRef": "col-2026-0001", "direction": "DEPOSIT",
      "currency": "USDC", "amount": "10000.000000", "sourceAsset": "USDe", "txRef": "0x9f3a6c1b", "occurredAt": 1788393600000,
      "status": "BOOKED", "refusal": "", "ledgerTxId": 10231, "createdAt": 1788393605000
    }
  }
}

balances is the client's USDC line after the booking: cash and reserved from the ledger, freeMargin from the risk engine (equal to cash while the client has no positions), free the lesser of the two (what a withdrawal could take now).

Refusal rules, in the order they are checked:

The enhanced due diligence (EDD) source-of-wealth ask. The ask is the SOURCE_OF_WEALTH block of PUT .../mifid (11.4) and nothing else: there is no second block, record, case or trigger name on the wire. It is an additional requirement on the money actions (DEPOSIT:CRYPTO and WITHDRAW:CRYPTO), whatever the client's level, once the client's cumulative deposits reach our threshold:

• The threshold is one risk parameter on our side, the same for every client: 500,000 EUR by default. Our ledger is in USDC, so the deposit sum is converted at an operator-maintained rate, a second risk parameter (0.92 EUR per USDC by default; it is not a market rate). At the defaults the threshold is reached at about 543,478 USDC of deposits, the same figure in your stablecoin because every collateral report is booked 1:1 in USDC. Our compliance function can change both parameters, so the values in force can differ from the defaults.
• The sum is the LIFETIME GROSS total of the client's deposits: every BOOKED collateral DEPOSIT report (under BROKER custody every confirmed deposit notice), plus any manual credit our finance desk books to the client's cash (a manual correction in the client's favour counts as one). There is no time window and a withdrawal NEVER reduces the sum; realised profits, funding, commissions, barrier settlements, swap flows and REFUSED reports never count.
• The check runs before the booking, on the sum as it stands: the deposit that crosses the threshold still books, and the NEXT report in either direction, a WITHDRAWAL included, is refused with 403 code 4030, data {action, level, requiredLevel: "MICA", missingBlocks: ["SOURCE_OF_WEALTH"]} and the msg "Because your total deposits have reached 500,000 EUR, we need to ask about the source of your wealth before the next deposit or withdrawal." (the threshold in force is inserted). No report row is written and no webhook fires on that refusal. Trading is not affected.
• The ask is satisfied while the block is SUBMITTED or APPROVED. PUT .../mifid writes the four MiFID blocks APPROVED in one step, whatever the appropriateness outcome, so a client you sent through PUT .../mifid never sees the ask, however much it deposits. It comes back only if our compliance later rejects that block (a verification decision naming it, or a rejected package, 16.4). A block our compliance rejected is under the compliance lock of section 11 (revision 14): the cure, the full four-block PUT .../mifid, answers 409 code 4092 until our compliance releases the block, so the collateral reports stay refused until then.
• A client you keep at level MICA, without a PUT .../mifid so far, CAN meet the ask. No partner route submits the SOURCE_OF_WEALTH block alone: the cure is the full four-block PUT .../mifid (11.4), after which the next report passes.
• The verification read carries no enhanced due diligence standing (no threshold, no deposit sum, no flag), so you cannot read how close a client is. The one advance signal is the requirements map of GET .../verification (11.5): once the ask applies, requirements["DEPOSIT:CRYPTO"] and requirements["WITHDRAW:CRYPTO"] list SOURCE_OF_WEALTH.
• On this route the gate is checked BEFORE the partnerRef replay (the order of the table above; the deposit notices and withdrawal requests of section 14 replay first). A retry of a report that was already BOOKED, sent without its original Idempotency-Key for a client who meets the ask by then, answers 403 code 4030 and not the original report (a retry under the original key replays the stored answer, section 5): read the report lists (15.2) before you treat that deposit as refused.

Reaching the threshold requests no documents by itself; supporting evidence is a matter of 10.3.

A partnerRef already filed for the SAME client is not a refusal: the original report replays (section 5). The four economic rows of a withdrawal are read under the client's lock inside the booking transaction (revision 4), so a fill or a mark move cannot slip in between the check and the booking. An economic refusal (the four rows that record a REFUSED report) answers the reason as msg and data: {reportId, status: "REFUSED", refusal, report}, fires collateral.refused, and moves nothing; the row stays in the lists as the partner's record of the attempt. Every booking fires collateral.booked. Both outcomes are noted on the client's and the partner's audit streams on our side.

Worked example: a withdrawal refused, then booked. Client 412 holds 10000 USDC of reported collateral and a 0.01 BTC-USD-PERP position bought at 60000 at 5x (initial margin 120, free margin 9880 at a mark of 60000):

1. {"partnerRef": "col-2026-0002", "direction": "WITHDRAWAL", "amount": "9900"} answers 409 code 4092, msg "The withdrawal exceeds the client's free margin.", data.reportId 502, data.status REFUSED; the client's cash is still 10000 and the webhook collateral.refused carries the report.
2. {"partnerRef": "col-2026-0003", "direction": "WITHDRAWAL", "amount": "9000"} answers 201 BOOKED with balances {"cash": "1000.000000", "reserved": "0.000000", "free": "880.000000", "freeMargin": "880.000000"} and the ledger transaction PARTNER_COLLATERAL_OUT; our house account partner_custody:7 now shows minus 1000, the collateral the partner still holds for the client per our books.
3. {"partnerRef": "col-2026-0002", "direction": "WITHDRAWAL", "amount": "1"} answers the original refusal again: 409 code 4092, msg "The withdrawal exceeds the client's free margin.", data.reportId 502 (the reference names that report for good; a new attempt needs a new reference), and nothing is written. A retry of step 2 under col-2026-0003 answers 200 with the same reportId and ledgerTxId, nothing booked twice.

15.2 Collateral report lists

GET /clients/{clientId}/collateral?status&limit&before and GET /partner/v1/collateral?status&limit&before (partner-wide): {reports: [<report>], hasMore, nextBefore}, newest first (keyset on the report id), status BOOKED or REFUSED (400 code 4000 otherwise), limit 1 to 200 (default 50).

15.3 Settlement items

Every ledger transaction that changes a PARTNER-custody client's USDC money with us (cash plus reserved), other than the collateral reports themselves and the withdrawal reserve mechanics, produces exactly ONE settlement item, written in the same database transaction as the posting: an item exists if and only if the posting does, and never twice (a replayed posting writes nothing more). A hold moved from cash to reserved and back (a spot reservation, a withdrawal reserve) is not a money change and produces no item; money leaving the reserved side (a swap principal, a spot delivery) is one. One economic fact can lead to more than one transaction over time, and so to more than one item: for example, a funding charge our reconciliation restates after the settlement is a further FUNDING transaction and a further item (the funding items, below).

amount is signed FROM THE CLIENT'S VIEW: positive = the partner must credit the client's stablecoin account by that amount, negative = the partner must debit it. type is the ledger transaction type and refs the transaction's own references:

Item lifecycle:

PENDING --report SETTLED (partnerTxRef)--> SETTLED
PENDING --report FAILED (note)-----------> FAILED --report SETTLED (the retry)--> SETTLED
SETTLED --report FAILED-------------------> refused, 409 code 4092
any status, the same status again --------> 200, changed: false (nothing rewritten)

The item is created PENDING with occurredAt = the posting time, and the webhook settlement.item_created fires from the same transaction. An item is owed between the firms the moment it exists (section 15.5); the partner's report only confirms that the client side was settled.

Worked example: a perpetual close. Client 412 buys 0.01 BTC-USD-PERP at 60000 and sells it reduce-only at 61000. The closing fill posts the realised P&L, and each fill posts its commission (0.30 in this example, whatever the commission scheme configured for the partner's clients charges); three items result:

{"itemId": 9101, "clientId": 412, "clientUid": "BARR-00000412", "partnerClientRef": "cust-001", "type": "COMMISSION", "currency": "USDC", "amount": "-0.300000",
 "refs": {"TradeId": 88001, "ClientOrderId": 4186, "Instrument": "BTC-USD-PERP"}, "occurredAt": 1788393700000, "status": "PENDING",
 "partnerTxRef": "", "settledAt": null, "reportedAt": null, "note": "", "ledgerTxId": 10240, "createdAt": 1788393700000}
{"itemId": 9102, "clientId": 412, "clientUid": "BARR-00000412", "partnerClientRef": "cust-001", "type": "PNL", "currency": "USDC", "amount": "10.000000",
 "refs": {"TradeId": 88002, "ClientOrderId": 4187, "Instrument": "BTC-USD-PERP"}, "occurredAt": 1788393760000, "status": "PENDING",
 "partnerTxRef": "", "settledAt": null, "reportedAt": null, "note": "", "ledgerTxId": 10242, "createdAt": 1788393760000}
{"itemId": 9103, "clientId": 412, "clientUid": "BARR-00000412", "partnerClientRef": "cust-001", "type": "COMMISSION", "currency": "USDC", "amount": "-0.300000",
 "refs": {"TradeId": 88002, "ClientOrderId": 4187, "Instrument": "BTC-USD-PERP"}, "occurredAt": 1788393760000, "status": "PENDING",
 "partnerTxRef": "", "settledAt": null, "reportedAt": null, "note": "", "ledgerTxId": 10243, "createdAt": 1788393760000}

The partner credits its client 10.00 USDe for item 9102, debits 0.30 twice for 9101 and 9103, and reports the three items (section 15.4). Between the firms the three net to +9.40: we owe the partner 9.40 (section 15.5). The opening fill realised nothing, so it produced its commission item alone.

Worked example: a barrier knock-out. Client 412 holds a long SP500-USD-KO contract 4711 on 2 units, entry 5000, barrier 4900, premium 200. The venue knocks the contract out AT the barrier: the settlement of minus 200 is exactly one item (the entry commission, when the scheme charges one, was its own COMMISSION item with refs {contractId, symbol} at the opening):

{"itemId": 9104, "clientId": 412, "clientUid": "BARR-00000412", "partnerClientRef": "cust-001", "type": "BARRIER_SETTLE", "currency": "USDC", "amount": "-200.000000",
 "refs": {"contractId": 4711, "symbol": "SP500-USD-KO", "reason": "knockOut", "settlePrice": "4900"}, "occurredAt": 1788397300000, "status": "PENDING",
 "partnerTxRef": "", "settledAt": null, "reportedAt": null, "note": "", "ledgerTxId": 10251, "createdAt": 1788397300000}

A contract that ends at its take profit produces the same item with a positive amount and reason takeProfit; an early close carries earlyClose and the accepted close price, an expiry expiry.

Worked example: a commission. A fill that opens or adds to a position realises nothing and produces its commission item alone, item 9101 above: type COMMISSION, a negative amount, the fill in refs. The partner debits the client and reports it like any other item.

The funding items (revision 22; the amount since revision 24). At every funding settlement of a perpetual market the venue charges us on our net position, and we pass the charge on to every client that held a position at the settlement, with the venue's own arithmetic (revision 24): minus the client's signed position times the settlement's markPrice times its fundingRate, rounded half-even to 6 places, plus the settlement's rounding remainder on ONE client of ours, often not one of yours (below); a long pays at a positive rate and a short receives; a charge that rounds to zero is not posted. That is one FUNDING item per client with a nonzero charge, normally created within minutes of the settlement, with refs {symbol, settledAt, qty, fundingPerUnit, side, fundingRate, markPrice, roundingRemainder}: symbol the market; settledAt the settlement's time in Unix ms (the venue's settlement instant that names it), not the item's own top-level settledAt, which is when the client side was settled, as your SETTLED report gives it (15.4; the report's own time is reportedAt); qty the client's position at the settlement as a SIGNED decimal string (negative for a short); fundingPerUnit the venue's figure in USD per unit, valued 1:1 in USDC, a DISPLAY figure: the venue rounds the charge of one lot to a millionth before it divides it by the lot, so qty times fundingPerUnit is NOT the amount (on a position of 10,000 at a mark of 76.37 and a rate of 0.0001 it gives 76.00 where the venue charged 76.37) and the amount is never computed from it; side LONG or SHORT; fundingRate and markPrice the venue's rate and mark of that settlement as the venue published them (decimal strings; the mark in USD per unit); roundingRemainder a JSON INTEGER in millionths of a USDC (not a decimal string), signed like amount, non-zero on at most ONE item of the settlement across ALL our clients, so usually 0 on every item you receive.

THE ROUNDING REMAINDER (revision 24). Each client's charge is rounded to the millionth on its own while the venue charges our net position once, so the venue's charge and the sum of our clients' rounded charges can differ, by less than one millionth per client of ours holding a position in that market. As the venue attributes it, that difference is carried by the ONE client of ours holding the largest position in that market at the settlement (the lowest of our clients on a tie), chosen across ALL our clients: our direct clients and the clients of every partner, not yours alone. So for most settlements every item you receive carries roundingRemainder 0; only the sum over ALL our clients is exactly what the venue charged us, never the sum of your items of a settlement, so never reconcile your items against the venue's charge or expect exactly one non-zero remainder among them. A non-zero roundingRemainder on one of your items means that your client held our largest position in that market at that settlement. So every item reproduces as:

amount = -round_half_even(qty x markPrice x fundingRate, 6 places) + roundingRemainder / 1,000,000

Before revision 24 the amount was minus qty times fundingPerUnit, rounded half-even to 6 places, with no remainder: a settlement we charged before the deployment of revision 24 keeps that amount and is never restated to the new one; its items carry the first five members alone, and a restatement of it (up to seven days after the settlement, below) is computed the earlier way, its refs without fundingRate, markPrice and roundingRemainder. One exception: a settlement whose charging a fault on our side interrupted before the deployment, and which we completed after it, is charged the new way, so its items posted before the deployment (the first five members alone) are restated to the new amount by a restatement item carrying the three members, with qty equal to previousQty, of the size of the difference between the two ways (0.37 on a position of 10,000 at a mark of 76.37 and a rate of 0.0001).

Restatements. Every few minutes our reconciliation re-derives the funding settlements of the last seven days (counted from the settlement's time or from the time we processed it, whichever is later) from the client's position at that settlement as our records hold it at that run. When that position changed after the charge (a fill of the client's that reached our records late from the venue, the source of truth, with a venue time before the settlement; or a corrected instant at which the positions of that settlement are measured), we never edit the earlier item: we post the DIFFERENCE as a further FUNDING transaction, and under PARTNER custody it is a settlement item of its own, with its own itemId, its own settlement.item_created delivery and occurredAt = the time of the restatement, hours or days after the settlement. Since revision 24 a client's charge is also restated by the rounding remainder alone (less than one millionth per client of ours holding a position in that market) when the position at that settlement of ANOTHER client of ours, yours or not, was restated and the remainder changed its size or moved to or from this client (such an item has qty equal to previousQty). Its refs are {symbol, settledAt, qty, previousQty, previouslyPosted, side, fundingRate, markPrice, roundingRemainder}:

There is no fundingPerUnit: the settlement's figure is the one on its first item. amount is the restated charge minus what was posted before, signed from the client's view like every item, so the restated charge is previouslyPosted / 1,000,000 plus amount. A charge restated to zero (side FLAT, or a position so small that its charge rounds to zero) yields an item of exactly minus previouslyPosted, which offsets the earlier items of that settlement; a restated position whose charge rounds to the same amount yields no item. One settlement can be restated more than once for the same client, each time as a further item. A client the re-derivation finds with a position at a settlement where it had no charge is charged late with an item of the FIRST shape (with fundingPerUnit), occurredAt the time of that run.

How to book the funding items:

• Key your item ledger by itemId (ledgerTxId is unique too), never by client, symbol and settlement: one client, market and settlement can carry several FUNDING items, the first and every restatement, and their sum is the client's net funding for that settlement.
• Never require fundingPerUnit, nor any member that only one of the two shapes carries: a restatement is the FUNDING item whose refs carry previouslyPosted. Never require fundingRate, markPrice or roundingRemainder either: they are absent on the items of a settlement charged before revision 24.
• To check an amount, reproduce it from fundingRate, markPrice and roundingRemainder (the formula above), never from fundingPerUnit.
• Never check that your items of one settlement sum to the venue's charge, nor that one of them carries a non-zero roundingRemainder: the remainder sits with one client across ALL our clients (above).
• Book a late item at its own occurredAt, in the period in which it was created, never back-dated to refs.settledAt: the item list's since, the summary and the interfirm block all read occurredAt (15.5).
• Settle and report it like any other item: it is owed between the firms the moment it exists and counts in the interfirm net like every item, whatever its status.

Worked example: a restated funding charge. Client 412 is long 0.5 BTC-USD-PERP at the settlement of 2026-11-04 08:00 UTC (settledAt 1793779200000), charged under revision 24, at a rate of 0.0001 and a mark of 60000 (fundingPerUnit 6): the charge is minus 0.5 x 60000 x 0.0001 = 3.00 (roundingRemainder 0: client 412 does not carry the settlement's rounding remainder), item 9105. Two hours later our reconciliation receives from the venue a sell of 0.3 the client made before the settlement: the restated position is 0.2, the restated charge minus 1.20, and item 9106 credits the difference, plus 1.80. Two days later a second late sell of 0.2 from before the settlement makes the position at the settlement flat: item 9107 credits plus 1.20, minus its previouslyPosted, with side FLAT:

{"itemId": 9105, "clientId": 412, "clientUid": "BARR-00000412", "partnerClientRef": "cust-001", "type": "FUNDING", "currency": "USDC", "amount": "-3.000000",
 "refs": {"symbol": "BTC-USD-PERP", "settledAt": 1793779200000, "qty": "0.5", "fundingPerUnit": "6", "side": "LONG", "fundingRate": "0.0001", "markPrice": "60000", "roundingRemainder": 0}, "occurredAt": 1793779260000, "status": "PENDING",
 "partnerTxRef": "", "settledAt": null, "reportedAt": null, "note": "", "ledgerTxId": 10260, "createdAt": 1793779260000}
{"itemId": 9106, "clientId": 412, "clientUid": "BARR-00000412", "partnerClientRef": "cust-001", "type": "FUNDING", "currency": "USDC", "amount": "1.800000",
 "refs": {"symbol": "BTC-USD-PERP", "settledAt": 1793779200000, "qty": "0.2", "previousQty": "0.5", "previouslyPosted": -3000000, "side": "LONG", "fundingRate": "0.0001", "markPrice": "60000", "roundingRemainder": 0}, "occurredAt": 1793786700000, "status": "PENDING",
 "partnerTxRef": "", "settledAt": null, "reportedAt": null, "note": "", "ledgerTxId": 10275, "createdAt": 1793786700000}
{"itemId": 9107, "clientId": 412, "clientUid": "BARR-00000412", "partnerClientRef": "cust-001", "type": "FUNDING", "currency": "USDC", "amount": "1.200000",
 "refs": {"symbol": "BTC-USD-PERP", "settledAt": 1793779200000, "qty": "0", "previousQty": "0.2", "previouslyPosted": -1200000, "side": "FLAT", "fundingRate": "0.0001", "markPrice": "60000", "roundingRemainder": 0}, "occurredAt": 1793952300000, "status": "PENDING",
 "partnerTxRef": "", "settledAt": null, "reportedAt": null, "note": "", "ledgerTxId": 10298, "createdAt": 1793952300000}

The three items sum to zero: in the end the client owed no funding for that settlement. The partner debits the client 3.00 for item 9105 and credits 1.80 and 1.20 for the other two, each in the period of its own occurredAt, and reports each one (15.4).

GET /partner/v1/settlement/items?status&since&clientId&limit&before: {items: [<item>], hasMore, nextBefore}, newest first (keyset on the item id). status one of PENDING, SETTLED, FAILED (400 code 4000 otherwise); since Unix ms, the items with occurredAt at or after it; clientId our numeric id or the client uid exactly as issued (section 7; 404 code 4004 for an unknown or foreign client); limit 1 to 500 (default 100). Poll status=PENDING after every settlement.item_created delivery, or on a schedule when you prefer pulling over webhooks.

15.4 Reporting settlement items

POST /partner/v1/settlement/items/{itemId}/report (TRADE, Idempotency-Key), body:

Answer 200 {item: <item>, changed: true}:

{"code": 0, "data": {"item": {"itemId": 9102, "clientId": 412, "clientUid": "BARR-00000412", "partnerClientRef": "cust-001", "type": "PNL", "currency": "USDC", "amount": "10.000000", "refs": {"TradeId": 88002, "ClientOrderId": 4187, "Instrument": "BTC-USD-PERP"}, "occurredAt": 1788393760000, "status": "SETTLED", "partnerTxRef": "usde-0x77c1", "settledAt": 1788394000000, "reportedAt": 1788394002000, "note": "", "ledgerTxId": 10242, "createdAt": 1788393760000}, "changed": true}}

State rules (pinned by our tests):

• The same status reported again answers 200 with changed: false and the item as it stands: the earlier partnerTxRef, settledAt and note are NOT rewritten.
• FAILED on a PENDING item records the note (settledAt null); a later SETTLED on it is the retry and is accepted.
• FAILED on a SETTLED item answers 409 code 4092 "This item was already reported SETTLED; it cannot be reported FAILED." with data.item.
• An unknown item id and another partner's item both answer 404 code 4004 "Unknown settlement item.".
• 400 code 4000: a status other than the two ("The status must be SETTLED or FAILED."), a missing or overlong reference on SETTLED ("partnerTxRef is required for a SETTLED report (1 to 128 characters)."), a settledAt in the future, a note over 500 characters.
• A report never changes the item's amount or the interfirm balance; it changes which bucket of the summary the item sits in.

POST /partner/v1/settlement/report (TRADE, Idempotency-Key), the bulk form, body {items: [{itemId, status, partnerTxRef?, settledAt?, note?}]} with 1 to 500 entries (400 code 4000 "items must carry 1 to 500 entries." otherwise). Every entry is applied on its own under the rules above; a refused entry does not stop the others. Answer 200:

{
  "code": 0,
  "data": {
    "results": [
      {"itemId": 9101, "ok": true, "changed": true, "status": "SETTLED"},
      {"itemId": 9102, "ok": true, "changed": false, "status": "SETTLED"},
      {"itemId": 9103, "ok": false, "code": 4092, "msg": "This item was already reported SETTLED; it cannot be reported FAILED."},
      {"itemId": 9999, "ok": false, "code": 4004, "msg": "Unknown settlement item."},
      {"itemId": 9104, "ok": false, "code": 4000, "msg": "The status must be SETTLED or FAILED."}
    ],
    "settled": 1, "failed": 0, "unchanged": 1, "refused": 3
  }
}

settled and failed count the entries that CHANGED an item to that status, unchanged the idempotent repeats, refused the entries with ok: false (an entry without itemId is refused with code 4000 "itemId is required."). With an Idempotency-Key the whole answer is replayed on a retry; without one a retry is harmless anyway, the repeats come back unchanged.

15.5 GET /partner/v1/settlement/summary?from&to

The settlement position per currency for a window (from and to Unix ms by the items' occurredAt; the defaults are the whole history up to now; 400 code 4000 unless 0 <= from <= to):

{
  "code": 0,
  "data": {
    "from": 0, "to": 1788480000000, "asOf": 1788480000000, "custodyModel": "PARTNER", "collateralAsset": "USDe",
    "currencies": [
      {
        "currency": "USDC",
        "pending": {"count": 3, "amount": "68.000000", "credits": "100.000000", "debits": "32.000000"},
        "settled": {"count": 0, "amount": "0.000000", "credits": "0.000000", "debits": "0.000000"},
        "failed": {"count": 0, "amount": "0.000000", "credits": "0.000000", "debits": "0.000000"},
        "collateralHeld": "1000.000000",
        "clientCash": "1068.000000",
        "interfirm": {"currency": "USDC", "owedToPartner": "100.000000", "owedByPartner": "32.000000", "net": "68.000000", "settlementsRecorded": "0.000000", "outstanding": "68.000000"}
      }
    ],
    "definitions": {
      "pending": "settlement items of the window not yet reported by the partner (count, signed sum, credits and debits apart)",
      "settled": "items the partner reported SETTLED",
      "failed": "items the partner reported FAILED (a later SETTLED report is a retry)",
      "collateralHeld": "minus the balance of HOUSE partner_custody:{partnerId}: the collateral the partner holds for our clients per our books, now (the BOOKED collateral reports plus the interfirm payments recorded, positive = we paid the partner)",
      "clientCash": "the sum of the partner clients' cash plus reserved, now; equals collateralHeld plus the interfirm outstanding over the whole history",
      "interfirm": {
        "owedToPartner": "the sum of the positive settlement items of the window (client gains the partner credited on our behalf)",
        "owedByPartner": "the sum of the negative settlement items of the window, as a positive figure (client losses and commissions the partner debited and owes us)",
        "net": "owedToPartner minus owedByPartner, signed: positive = we owe the partner, negative = the partner owes us",
        "settlementsRecorded": "the interfirm settlements finance recorded whose period OVERLAPS the window (periodFrom <= to and periodTo >= from), each counted in full, signed: positive = we paid the partner",
        "outstanding": "net minus settlementsRecorded: what is still to be paid, signed like net",
        "window": "settlement items by occurredAt, every status (a PENDING item is owed as soon as it exists; the partner's report only confirms it)"
      }
    }
  }
}

The three buckets carry the count, the signed sum (amount), and the credits (the positive items) and debits (the negative items, as a positive figure) apart. collateralHeld and clientCash are figures as of now, not of the window; clientCash is what our ledger holds for the partner's clients (cash plus reserved) and equals the collateral held plus the outstanding interfirm balance over the whole history (1000 + 68 in the example before any payment; after finance pays 50, collateralHeld reads 1050 and outstanding 18), because every interfirm record moves collateralHeld by the payment (revision 10; before it the identity read the net of every item ever produced). The definitions travel in every answer.

The interfirm block. From OUR point of view: the positive items are client gains the partner credited on our behalf (owedToPartner), the negative items are client losses and our commissions the partner debited and owes us (owedByPartner); net is the difference, signed (positive = we owe the partner). Our finance records each interfirm payment (section 15.6); settlementsRecorded is the sum of the recorded settlements whose period overlaps the window, each counted in full (revision 6; positive = we paid the partner), and outstanding = net minus settlementsRecorded is what is still to be paid, signed like net.

Worked example: the summary and the interfirm balance. One client, a collateral deposit of 1000, then three items: a realised profit of +100, a realised loss of -30 and a commission of -2, all PENDING. The summary shows pending {count: 3, amount: "68.000000", credits: "100.000000", debits: "32.000000"}, collateralHeld 1000, clientCash 1068, and interfirm {owedToPartner: "100.000000", owedByPartner: "32.000000", net: "68.000000", settlementsRecorded: "0.000000", outstanding: "68.000000"}: we owe the partner 68. The partner reports the +100 item SETTLED and the -30 item FAILED: the buckets become pending {1, -2.000000}, settled {1, 100.000000}, failed {1, -30.000000}, and net stays 68 (a report never moves the interfirm balance). Our finance then pays the partner 50 for the period and records it: net 68, settlementsRecorded 50, outstanding 18 and collateralHeld 1050 (revision 10: the record posts the payment into the mirror, partner_custody:<partnerId> against partner_interfirm:<partnerId>). A window that ends before the items and the recorded period counts neither; a window that covers the items and ANY part of the recorded period counts both (revision 6: a record counts in full in every window its period overlaps; before, only in a window containing the whole period), so a window cut through a settled period still shows the payment against the items it shows. Agree the period boundaries with our finance all the same, so that a payment and the items it settles fall in the same windows.

15.6 GET /partner/v1/settlement/interfirm?limit&before

The interfirm settlements our finance recorded, newest first (limit 1 to 500, default 50, keyset on the settlement id):

{
  "code": 0,
  "data": {
    "settlements": [
      {"settlementId": 12, "partnerId": 7, "currency": "USDC", "periodFrom": 1787788800000, "periodTo": 1788393599999, "amount": "50.000000", "direction": "PAID_TO_PARTNER",
       "txRef": "wire-2026-09-02-0001", "note": "first half of the week", "recordedBy": "finance.ops", "recordedAt": 1788480000000, "ledgerTxId": 9107}
    ],
    "hasMore": false, "nextBefore": null,
    "definitions": {"owedToPartner": "...", "owedByPartner": "...", "net": "...", "settlementsRecorded": "...", "outstanding": "...", "window": "..."}
  }
}

amount is signed like settlementsRecorded (positive = we paid the partner, direction PAID_TO_PARTNER; negative = the partner paid us, PAID_BY_PARTNER). A record is written by our finance from the back office with the payment reference; the partner cannot create or change one. A payment is recorded once: the record is idempotent on its payment reference (txRef) per partner, so a retried entry never doubles a payment (revision 6). The summary subtracts a record from every window its period overlaps (section 15.5). ledgerTxId (revision 10) is the ledger posting bound to the record on our books (one per record, written with the record; the collateral we hold per our books, collateralHeld of 15.5, moves by the payment: the BOOKED collateral reports plus the payments recorded, positive = we paid the partner); null only on a record written before revision 10 and not yet backfilled by our finance.

15.7 What happens on our side

• Every collateral report and every settlement report is noted on the partner's audit stream and, where a client is involved, on the client's; every interfirm record is audited with the recording employee and posts its ledger transaction in the same database transaction (15.6).
• A PENDING item older than 48 hours, or any FAILED item, opens one compliance case per partner per UTC day on our side, and our back office shows the pending count and the oldest pending age per partner. Settle and report items promptly; report a FAILED item with a note that says why, and retry it with SETTLED once the client side is fixed.
• The second tier (revision 10): an item PENDING or FAILED for more than 120 hours by default, or an unsettled net (the absolute value of the signed sum of the PENDING and FAILED items) above the lower of a USDC cap and a percentage of collateralHeld, both operator parameters fixed in the partner agreement, puts the partner's clients in close-only: an opening order, a barrier request or the accept of an opening request, and a staking take answer 403 code 4041 PARTNER_CLOSE_ONLY (section 4; over FIX 9110=4041), while a reducing order, an early close, the collateral and settlement reports and every read keep working. The state lifts on our hourly check once every item older than the escalation age is settled and the unsettled net is back under the cap (a SETTLED report does not lift it at once); the day's compliance case is escalated on our side. GET /me is unchanged.
• The partner agreement sets the contractual standard: each item is settled and reported SETTLED by the end of the Business Day following its creation and in any event within 48 hours; a FAILED report does not discharge the item; a correction is a new item, never a change of an existing one: a MANUAL item from our finance, or a further item our reconciliation posts when it restates a posting (for example a FUNDING restatement, 15.3, revision 22). Suspension (code 4037) remains a separate manual measure.
• The settlement report of section 14.3 stays available and carries the same interfirm block, so a reconciliation built for BROKER custody keeps working for a PARTNER-custody partner.

16. Webhooks

16.1 Registration

PUT /partner/v1/webhook (TRADE), body {url} (an absolute https URL): registers or replaces the endpoint and answers the signing secret ONCE. Every PUT rotates the secret, so a PUT is also the rotation procedure (deploy the new secret to your verifier before the next delivery arrives: deliveries already queued are signed with the secret current at send time).

The URL must point at a PUBLIC host (revision 5): https only (400 code 4000 "The webhook URL must be an absolute https URL."), and the host, an IP literal or a name resolved at registration, may not be a loopback, private (10/8, 172.16/12, 192.168/16, the shared 100.64/10 space, IPv6 unique local), link-local, multicast or otherwise unroutable address, nor localhost; a name that resolves to any such address, or to nothing, is refused (400 code 4000 "The webhook host must resolve to a public address (no loopback, private, link-local or multicast address)." or "The webhook host does not resolve."). The check runs again before every delivery and once more when the connection is dialled, so a name that later resolves inside our network is refused rather than delivered (the delivery log shows the sentence as the error). Any port is accepted.

{"code": 0, "data": {"url": "https://partner.example/hooks/barriers", "secret": "whs_4c1d2e3f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d", "active": true, "createdAt": 1788307200000, "updatedAt": 1788312300000}}

GET /partner/v1/webhook: {url, active, createdAt, updatedAt, lastDeliveryAt, pending, maxPending} (404 code 4004 when none is registered). pending is the number of deliveries not yet sent and still within their attempts; maxPending (revision 8) the count at which further rfq.quote events are dropped (section 16.3): the distance between the two is how far you are from losing quotes; lastDeliveryAt the newest delivery sent within the kept log.

The delivery log is kept 30 days (our configuration Partners:WebhookRetentionDays): a SENT or FAILED delivery older than that leaves the log and the list below (a FAILED delivery can no longer be redelivered once it left); a delivery still PENDING or RETRYING is never removed, whatever its age. DELETE /partner/v1/webhook: deactivates ({active: false, updatedAt}); events are not queued while inactive; a later PUT reactivates with a new secret. POST /partner/v1/webhook/test: enqueues a webhook.test delivery, {deliveryId, event, queuedAt}; 409 code 4092 while inactive. Since revision 17 the route takes an OPTIONAL JSON body that asks for a SAMPLE of a questionnaire event instead: {event: "appropriateness_test.version_changed", stage} with stage one of ANNOUNCED, IN_FORCE, WITHDRAWN, GRACE_ENDED, or {event: "appropriateness_test.text_changed", kind} with kind one of LOCALE_ADDED, TEXT_CORRECTED, TEXT_WITHDRAWN; the answer is {deliveryId, event, stage or kind, sample: true, queuedAt} and the delivery carries data.sample: true (section 18 says what a sample's data names). A body without an event member is today's test (no body, an empty one, {} and any other object deliver webhook.test); a body that is not JSON answers 400 code 4000; an event that names no sample answers 400 code 4000 "event names no sample we deliver.". Use a new Idempotency-Key per sample: the same key with another {event, stage} or {event, kind} is another request and answers 409 code 4092 (section 5; before revision 20 it replayed the first sample). GET /partner/v1/webhook/deliveries?limit&before: the delivery log, newest first, limit 1 to 200: {deliveries: [{deliveryId, event, clientId, clientUid, status, attempts, lastStatus, error, ts, sentAt, nextAt}], hasMore, nextBefore} with status PENDING, RETRYING, SENT, FAILED.

16.2 Delivery

Each event is one POST to your URL with Content-Type: application/json and the headers

Body:

{
  "id": 5120,
  "event": "deposit.confirmed",
  "partnerId": 7,
  "clientId": 412,
  "clientUid": "BARR-00000412",
  "partnerClientRef": "cust-001",
  "ts": 1788312400000,
  "data": {"noticeId": 77, "partnerRef": "dep-2026-0001", "currency": "USDC", "amount": "1500.000000", "status": "CONFIRMED", "ledgerTxId": 9950}
}

clientId, clientUid and partnerClientRef are null on partner-level events: webhook.test and, since revision 17, the two questionnaire events appropriateness_test.version_changed and appropriateness_test.text_changed (16.4), which are delivered once per partner and never per client. ts is the time the event was queued. A settlement item, for example:

{
  "id": 5231, "event": "settlement.item_created", "partnerId": 7, "clientId": 412, "clientUid": "BARR-00000412", "partnerClientRef": "cust-001", "ts": 1788393760000,
  "data": {"itemId": 9102, "clientId": 412, "clientUid": "BARR-00000412", "partnerClientRef": "cust-001", "type": "PNL", "currency": "USDC", "amount": "10.000000",
           "refs": {"TradeId": 88002, "ClientOrderId": 4187, "Instrument": "BTC-USD-PERP"}, "occurredAt": 1788393760000, "status": "PENDING", "partnerTxRef": "", "settledAt": null, "reportedAt": null, "note": "", "ledgerTxId": 10242, "createdAt": 1788393760000}
}

Answer any 2xx status within 10 seconds to acknowledge; the response body is ignored (on a failure at most 16 KiB of the body is read and at most 256 bytes of it are kept as the error text of the delivery log). A redirect (3xx) is never followed: it counts as a failed attempt. Deliveries can arrive out of order and, after a timeout on your side, more than once: deduplicate on id.

16.3 Retry policy

A non-2xx answer, a timeout (10 s) or a connection failure schedules a retry after 5 s x 2^n where n is the number of attempts so far, capped at 2^7: 10 s, 20 s, 40 s, 80 s, 160 s, 320 s, 640 s, 640 s, 640 s. After 10 attempts the delivery is FAILED and stays in the log for the kept 30 days (16.1); our operations team can redeliver it from the back office while it is there. The worker runs every 5 seconds and a delivery is claimed by one worker instance at a time (a claim older than 60 s is taken over).

Deliveries run per partner: each pass of the worker takes the due deliveries of every partner, at most 50 per partner, with every other event ahead of rfq.quote (a margin call or a fill never waits behind a quote backlog of yours), since revision 28 rfq.quote ahead of every perpetual demo event (demo.*, 23.9), and oldest first within each class, and posts them partner by partner, the partners in parallel and one delivery at a time within a partner. A timeout or a connection failure on your endpoint ends your turn for that pass (the deliveries after it stay queued and are attempted on the next pass), so an endpoint that is down costs one timeout per pass and never delays another partner, and no other partner's outage delays you. The order within a class is the queue order, so rfq.quote of one request can still overtake a later rfq.quote of another after a retry: order by the object's own timestamps (16.4) and deduplicate on id.

The pending cap (revision 8; since revision 28 it counts LIVE deliveries only): when your pending live deliveries (every event but the perpetual demo's demo.* events of 23.9) reach maxPending (5000 by default, our configuration Partners:WebhookMaxPending, never below 100), further rfq.quote events are DROPPED, not queued, and our log records the drops (one line per partner per minute). No other live event is ever dropped: a margin call, a fill or a contract close is worth a long queue, while a quote is the only event you can re-read without loss (GET .../rfq/{rfqId} carries every live quote). On the development venue a market maker connected to it quotes every barrier request within seconds, so an endpoint that stays down for hours would otherwise accumulate a quote per request per maker indefinitely. Since revision 28 the perpetual demo's demo.* events (23.9) are never counted toward it, so demo traffic never costs you a quote, while pending on GET /webhook counts every pending delivery, the demo's included, and can read above the live count the cap compares with. The demo's own cap (1,000 pending deliveries of every event, never above this one) drops further demo events alone (23.9).

16.4 Event catalogue

Explicit events (the data object):

A partner MUST ignore event names it does not handle: new events are added to the catalogue without a version change of the endpoint.

Perpetual demo events (revision 28): the eight demo.* names of section 23.9 (demo.order.filled, demo.order.triggered, demo.order.canceled, demo.margin.call, demo.margin.call_cleared, demo.close_out.started, demo.close_out.done, demo.account.deleted) report the simulated accounts of section 23. They are never among the names of this catalogue, no live event ever carries a demo fact, every demo event's data carries demo: true, and they are delivered after every live event and after rfq.quote (16.3), best effort.

Life-cycle events (revision 8, the addendum of 2026-09-06): explicit, emitted at the state change itself, never derived from the notification feed, and each exactly once per fact (the delivery may still repeat after a timeout on your side: deduplicate on id). Money is a 6-place decimal string in USDC, prices and quantities decimal strings, times Unix milliseconds, as on the reads they mirror. Deliveries can arrive out of order: order by the object's own timestamps (updatedAt, closedAt, at) and deduplicate on the envelope id.

The data of margin.call, margin.call_cleared, margin.close_out_started and margin.close_out_done (from and to are NORMAL, MARGIN_CALL, CLOSE_OUT; marginLevel is null when no margin is used; on the forced start every figure is null and forced is true; riskEventId names the risk event on our side, at the time of the transition; on margin.close_out_done the figures are the snapshot at the tick that found the account flat):

{
  "from": "NORMAL", "to": "MARGIN_CALL",
  "equity": "812.500000", "marginLevel": "90.28", "initialMargin": "900.000000", "maintenanceMargin": "450.000000",
  "marginCallPct": "100", "closeOutPct": "50",
  "marginCallLevel": "900.000000", "closeOutEquity": "812.500000", "cash": "1000.000000", "unrealizedPnl": "-187.500000",
  "riskEventId": 90231, "forced": false, "at": 1788400000000
}

(The example is a long 0.03 BTC-USD-PERP opened at 60,000 at leverage 2 with 1,000 USDC of cash, marked at 53,750: the initial margin is the margin required to open, 0.03 x 60,000 / 2 = 900, not 0.03 x 53,750 / 2 = 750 as before 11 September 2026, so the call is raised at 900 and the close-out level is 450.)

There is no notice period between margin.call and margin.close_out_started. The close-out starts on the first tick that finds closeOutEquity strictly below maintenanceMargin, whether or not a margin call was recorded before it (a margin.close_out_started with from: "NORMAL" is that case); the margin call at marginCallPct of the perpetual margin (100 by default) is the notice, and attached stop loss legs are the client's own protection.

The data of order.accepted, order.partially_filled, order.filled, order.canceled and order.rejected: the order of GET .../orders (section 12.3) read after the change, flattened, plus fill (the fill on the two fill events, null otherwise), reason (canceled or expired on order.canceled, the reject sentence on order.rejected, null otherwise) and rejectCode (the venue code on order.rejected, null when the frame carried none, null otherwise):

{
  "orderId": 4185, "clOrdId": "BARR-4185", "symbol": "BTC-USD-PERP", "family": "PERP", "side": "BUY", "type": "LIMIT", "qty": "0.5", "price": "64250.0",
  "state": "PARTIAL", "reject": null, "filledQty": "0.2", "createdAt": 1788311500000, "reduceOnly": false, "tif": "GTC", "trigger": null, "updatedAt": 1788311600120,
  "attach": null, "ocoGroup": null, "parentOrderId": null, "parentClOrdId": null, "origin": "CLIENT", "note": null, "replacedBy": null, "replaces": null, "reservation": null,
  "channel": "REST", "channelKeyId": null, "channelRef": null,
  "fill": {"tradeId": 88002, "price": "64250.0", "qty": "0.2", "commission": "1.285000", "realizedPnl": "0.000000", "role": "MAKER", "ts": 1788311600100},
  "reason": null, "rejectCode": null
}

An order your app placed with an app order command (section 22) fires the same five events from the same sites, with channel APP and channelRef the token's jti (12.3); a cancel or a leverage change sent from the app fires what the same change sent over /partner/v1 fires. The app order routes themselves answer your app, never your webhook: the events are how your backend learns what the app did.

The data of rfq.quote (premium is the maximum loss at the quoted entry, the wire's impliedPremium; acceptable and notAcceptableReason by the same rule the request's quotes carry; expiresAt the quote's validity; on a close request closeContractId names the contract and premium and impliedLeverage are null):

{
  "rfqId": 311, "venueRfqId": 5207, "symbol": "BTC-USD-KO", "side": "BUY", "closeContractId": null,
  "quoteId": 902, "price": "65471.5", "qty": "1", "premium": "2224.350000", "premiumBps": 9000, "impliedLeverage": "26.49",
  "acceptable": true, "notAcceptableReason": null, "expiresAt": 1788311470000, "autoAccept": true, "seenAt": 1788311428000
}

The data of rfq.accepted (premium null and closeContractId set on an early close; commission the entry commission on an opening accept and, since revision 10 (BROKER-14), the early-close commission on a close accept; tradeId the venue trade id, null when the venue's answer carried none):

{"rfqId": 311, "quoteId": 902, "contractId": 4711, "closeContractId": null, "entry": "65471.5", "premium": "2224.350000", "commission": "22.243500", "tradeId": 771310, "symbol": "BTC-USD-KO", "side": "BUY", "qty": "1"}

The data of rfq.expired, rfq.canceled and rfq.rejected (state the request's terminal state EXPIRED, CANCELLED or REJECTED; reason the sentence the request carries as rejectReason, for example "The request was withdrawn at the trading venue.", "This contract is no longer open." on a close request whose contract ended first, or "This market is not currently offered." on an opening request our operator withdrew when the market was disabled (revision 10, BROKER-84), null on a plain expiry; rejectCode the venue's code on a create-time refusal):

{"rfqId": 311, "state": "EXPIRED", "reason": null, "rejectCode": null, "closeContractId": null}

The data of barrier.closed (reason is knockOut, takeProfit, expiry, earlyClose, tearUp or other; closeReason the contract's own value as GET .../barriers?state=history shows it, liquidation for a tear-up, finalSettlement, reconciler:ledger on a close inferred from the venue ledger; side the request side and direction the holder direction; pnl the settled result, premium the maximum loss, commission the opening commission and, since revision 10 (BROKER-14), closeCommission our early-close commission (0.000000 on every other close); closeTradeId the venue trade id of an early close, null otherwise, and null when the venue's close frame settled the contract before the accept answer stamped the id, whichever lands first settles: GET .../barriers?state=history carries it once the answer landed, and the contract read is the final record):

{
  "contractId": 4711, "symbol": "BTC-USD-KO", "side": "BUY", "direction": "LONG", "qty": "1", "entry": "65471.5", "barrierLevel": "63000", "takeProfit": "66500",
  "reason": "knockOut", "state": "KNOCKED_OUT", "closeReason": "knockOut",
  "settlePrice": "63000", "pnl": "-2224.350000", "premium": "2224.350000", "commission": "22.243500", "closeCommission": "0.000000",
  "openedAt": 1788311428000, "closedAt": 1788390000000, "rfqId": 311, "closeTradeId": null
}

The data of client.categorization_changed (section 11.6; status APPLIED, REJECTED or REVOKED; basis ELECTIVE or PER_SE; categorization the client's categorisation AFTER the event, unchanged on REJECTED, RETAIL on REVOKED; requestId null on a revocation no applied request produced; a withdrawal fires nothing; an applied opt-down is one APPLIED event with to: "RETAIL", the professional request it ends is closed on the file without a second event):

{"requestId": 77, "from": "RETAIL", "to": "PROFESSIONAL", "status": "APPLIED", "basis": "ELECTIVE", "decidedAt": 1788390000000, "effectiveAt": 1788476400000, "appliedAt": 1788476400000, "reviewAt": 1820012400000, "categorization": "PROFESSIONAL"}

The data of client.consent_required (section 10.5, revision 10): a new version of a consent document the client has to accept, at two instants at most per version and client, stage ANNOUNCED (the publication of a version effective later; reconsentRequired is then the client's standing at that instant, usually false since the version is not yet in force) and IN_FORCE (the version came into force and the client's standing does not name it, reconsentRequired true); gateFrom the instant the TERMS re-consent gate would refuse new positions (null while the document is not gated or our switch is off); the source reference is consent:{versionId}:{clientId}:{stage}, so a repeat is a no-op:

{"clientId": 512, "clientUid": "BARR-00000512", "partnerClientRef": "sb-usr-10457", "doc": "TERMS", "title": "Terms and Conditions", "url": "https://barriers.com/legal/terms",
 "version": "2026-10", "effectiveAt": 1791158400000, "gateFrom": 1793750400000, "stage": "IN_FORCE", "reconsentRequired": true}

The data of incident.notice (revision 10, BROKER-39): our compliance function sent the client the DORA Article 19(3) service incident notice (a major ICT or operational incident on our side that affected the client's financial interests), by e-mail on our side; the event carries the incident register entry's reference, title and status (OPEN, CONTAINED, RECOVERED), its detection and recovery instants (recoveredAt null while not recovered), and the rendered notice the client received (subject, text: the same wording, so you mirror it to the client you introduced verbatim in your app or by your own channel; never our internal description, root cause or lessons), with sentAt the instant it was queued. One event per incident and client; the source reference is incident:{entryId}:{clientId} (written incident:{entryId}:client:{clientId}), so a repeat is a no-op:

{"ref": "INC-2026-0003", "title": "Order entry outage", "status": "CONTAINED", "detectedAt": 1789000000000, "recoveredAt": null,
 "subject": "Service incident notice INC-2026-0003", "text": "Service incident notice. On 2026-09-10 at 09:12 UTC we detected an incident affecting order entry on the barriers platform. ...", "sentAt": 1789003600000}

Events derived from the client's notification feed (the same items GET .../notifications lists), data: {kind, ref, ts} where ref is the id of the object the notification is about:

The feed is swept every 5 seconds per partner with an active webhook; the first sweep after activation starts at "now" (nothing older is sent). Each sweep re-reads the last 30 seconds of the feed (revision 5), so an item whose record was written a little after the time it carries is still forwarded; the re-read never produces a second delivery of the same item (one row per item per client), but an item written more than 30 seconds after its own timestamp is not forwarded: poll the feed for those. The life-cycle events above never come from the feed and have no feed item; GET .../rfq, GET .../barriers and GET .../orders/open remain the reads to converge on when a delivery failed for good.

Reading a verification decision. client.verification_decision carries {kind: "VERIFICATION_DECISION", ref, ts} and nothing else: no level, no approved or refused flag. Re-read GET .../verification (11.5) in the handler: the level, the block statuses and, on a refused block, the client-facing sentence in blocks[].reason are there. A downgrade (our compliance refusing the MiFID level of a client at MICA_MIFID: the level goes back to MICA and the blocks named in the decision read REJECTED) and a level our compliance grants in our back office reach you as this event ONLY; client.level_changed never fires for them. A rejected package (kyc.rejected: every block REJECTED, level NONE) records no verification decision, so no client.verification_decision follows it. The MiFID blocks a refusal names are locked against your MiFID writes until our compliance releases them, and the release fires no event (revision 14, the introduction of section 11): re-read GET .../verification.

No expiry event. The catalogue has no expiry event because nothing expires (10.6). The identity document pause reaches you as margin.restriction_set and margin.restriction_lifted; our periodic review fires nothing by itself.

A restriction cannot be read on this API today. margin.restriction_set carries the restriction's id and nothing about its kind (NO_NEW_ORDERS, CLOSE_ONLY, NO_WITHDRAWALS, FROZEN; an information-only kind without any trading or money effect exists too, so an event need not be followed by a refusal), its family or its ground. GET .../verification has no restrictions member, GET /trading-status (12.1) answers the venue-wide halts only, and the notification item is {kind, ref, ts, event}. You learn of a restriction from the event, and of its effect from the sentence the client's next refused request carries (11.4, 15.1).

The two questionnaire events (revision 17). Both are PARTNER LEVEL: the envelope's clientId, clientUid and partnerClientRef are null, one delivery reaches every partner with an active webhook (a sandbox partner too), and nothing is delivered per client. The data of appropriateness_test.version_changed is {stage, version, previousVersion, currentVersion, publishedAt, effectiveAt, previousAcceptedUntil, changeClass, renderingChanged, sentencesChanged, changedQuestionIds, changeNote, urgent, rehearsal, textHash, availableLocales, read}: stage one of ANNOUNCED, IN_FORCE, WITHDRAWN, GRACE_ENDED; version the version the stage is about; previousVersion its predecessor; currentVersion the version in force at the emit (after a WITHDRAWN above all; on a LATE IN_FORCE notice, one delivered after the version's instant, the version itself, its successor's notice following); previousAcceptedUntil the instant until which the previous version is accepted once version is in force (exclusive; equal to effectiveAt when nothing is accepted; moved by a GRACE_ENDED); the schedule members as on 11.1; read the path of the read that serves the version (/partner/v1/appropriateness-test?version=N). The data of appropriateness_test.text_changed is {kind, family, version, locale, textRevision, textHash, previousTextHash, previousAcceptedUntil, correctionClass, defective, read}: kind one of LOCALE_ADDED, TEXT_CORRECTED, TEXT_WITHDRAWN; family the family of the words, APPROPRIATENESS_TEST for the questionnaire (the only texts that change today; for the reserved languageElection block of 11.1 the family is LANGUAGE_ELECTION, version the master version of that sentence and read the questionnaire read of the version in force, on which the block is served); version the questionnaire version whose words changed; locale the language; textRevision and textHash the text now served (null on a TEXT_WITHDRAWN that leaves the language unserved); previousTextHash the text replaced; previousAcceptedUntil the instant until which the replaced text is still accepted on a submission (exclusive; null on LOCALE_ADDED); correctionClass COSMETIC or MATERIAL on a TEXT_CORRECTED; defective on a TEXT_WITHDRAWN; read the path of the read that serves the words (/partner/v1/appropriateness-test?version=N&locale=xx). An ANNOUNCED delivery, for example:

{
  "id": 6310, "event": "appropriateness_test.version_changed", "partnerId": 7, "clientId": null, "clientUid": null, "partnerClientRef": null, "ts": 1790845200000,
  "data": {"stage": "ANNOUNCED", "version": 2, "previousVersion": 1, "currentVersion": 1, "publishedAt": 1790845200000, "effectiveAt": 1793577600000, "previousAcceptedUntil": 1793581200000,
           "changeClass": "STRUCTURE", "renderingChanged": true, "sentencesChanged": true, "changedQuestionIds": ["strictTakeProfitKnowledge"], "changeNote": "One knowledge question added and the warning sentence extended.",
           "urgent": false, "rehearsal": false, "textHash": "sha256:<the hash of the announced version's English text>", "availableLocales": ["en"], "read": "/partner/v1/appropriateness-test?version=2"}
}

and a LOCALE_ADDED sample as the development environment delivers it on request (section 18; a sample carries data.sample: true and names the pseudo locale qps, never a real language):

{
  "id": 6311, "event": "appropriateness_test.text_changed", "partnerId": 7, "clientId": null, "clientUid": null, "partnerClientRef": null, "ts": 1790845260000,
  "data": {"kind": "LOCALE_ADDED", "family": "APPROPRIATENESS_TEST", "version": 1, "locale": "qps", "textRevision": 0, "textHash": "sha256:<the hash of the pseudo text>", "previousTextHash": null,
           "previousAcceptedUntil": null, "correctionClass": null, "defective": false, "read": "/partner/v1/appropriateness-test?version=1&locale=qps", "sample": true}
}

A text_changed sample of the declarations family is delivered on request too (section 18; POST /webhook/test {event, kind, family} since revision 18): it names family DECLARATIONS_MIFID, version 1 and read /partner/v1/texts?family=DECLARATIONS_MIFID&locale=qps.

New stage, kind and family values may be added; ignore one you do not handle. Deliveries can arrive out of order and twice, so on any appropriateness_test.* event re-read the path read names and trust the read (11.1 for the questionnaire, 11.7 for the declarations): the read is the truth, the event the signal to re-read and to drop your cache.

16.5 Signature verification

Recompute the signature over the RAW request body (the bytes as received, before any JSON parsing) and the timestamp header, compare in constant time, and refuse a timestamp more than 300 seconds from your clock (replay protection). Node.js:

import { createHmac, timingSafeEqual } from "node:crypto";

// secret: the whs_ value answered by PUT /partner/v1/webhook.
// rawBody: the request body as a UTF-8 string, byte for byte.
export function verifyBrokerageWebhook(secret, headers, rawBody, nowMs = Date.now(), maxSkewSeconds = 300) {
  const ts = headers["x-brokerage-timestamp"];
  const given = String(headers["x-brokerage-signature"] ?? "").trim().toLowerCase();
  if (!/^\d+$/.test(String(ts ?? ""))) return "missing or malformed timestamp";
  if (Math.abs(Math.floor(nowMs / 1000) - Number(ts)) > maxSkewSeconds) return "timestamp outside the accepted window";
  const expected = "v1=" + createHmac("sha256", secret).update(`${ts}.${rawBody}`, "utf8").digest("hex");
  const a = Buffer.from(given, "utf8"), b = Buffer.from(expected, "utf8");
  if (a.length !== b.length || !timingSafeEqual(a, b)) return "signature mismatch";
  return null; // verified
}

Answer 200 only after the verification passed; process the event asynchronously if your handling takes longer than a few seconds.

17. Statements

The four stored statement kinds our clients get in the portal are available per client, built from the ledger, fills, contracts and funding: ACCOUNT (opening balance, every posting with a running balance, closing balance), COSTS (the ex-post costs and charges disclosure), TRANSACTIONS (the transaction confirmations; we generate the previous UTC day's statement nightly for every client with activity and issue an updated version automatically, generatedBy SYSTEM with supersedes set, when the day's records change after it), TAX (calendar year, or 6 April to 5 April for a GB tax residency) and CLIENT_ASSETS (the quarterly client assets statement).

• GET /clients/{clientId}/statements?kind&limit: (bare) {statements: [{id, clientId, kind, periodFrom, periodTo, basis, generatedAt, generatedBy, title, formats, pdfBytes, sha256, version, supersedes, supersededBy}]}, newest first, limit 1 to 200. A statement row names its client by clientId only, without clientUid or partnerClientRef (revision 25, section 7).
• POST /clients/{clientId}/statements (TRADE), body {kind, preset, from, to, year}: preset one of LAST_30_DAYS, LAST_MONTH, THIS_YEAR, LAST_YEAR, CUSTOM (with from and to, YYYY-MM-DD, at most 24 months), SINCE_LAST_STATEMENT, LAST_QUARTER, THIS_QUARTER; year for TAX (up to 5 years back). Answers the new row (bare). 30 generations per client per hour (429 code 4290).
• GET /clients/{clientId}/statements/{sid}: the row with its model (bare). The model's account names the client by clientId and by the uid as clientRef, the uid the PDF prints beside the client's name: an opaque uid like any other (section 7), to be matched as served.
• GET /clients/{clientId}/statements/{sid}/pdf and /csv: the file as an attachment (application/pdf, text/csv); 404 code 4004 when the kind offers no CSV.

Statement PDFs are deterministic (the model's SHA-256 is in the footer and in sha256); a statement is never deleted, a correction is a new version that names the one it supersedes.

The custody caveat of the quarterly CLIENT_ASSETS statement: its balances note and its MiCA note read the partner's custody model (section 13). Under BROKER custody the client's money is with us and the notes say so. Under PARTNER custody the USDC balance is described as the mirror, one to one, of the collateral you hold for the client under your own licence as your collateralAsset ("its own stablecoin" when none is recorded), PM MTF Ltd as holding no funds for the client, the economic results of the client's trading as settled between you and the client in that asset, and only the client's crypto-asset holdings and the part of its balance deployed as margin or for delivery as recorded on PM MTF Ltd's member account at the Kronos X MTF; the statement of position for the mirrored crypto-asset is yours, and the statement stays the client's statement of position for its spot holdings under MiCA. The shared disclaimer and every other kind are unchanged.

18. Sandbox behaviour

"Sandbox" here is the partner flag of this section and the development environment, never the perpetual demo of section 23 (revision 28): the orders of a sandbox partner's clients go to the development venue like every order and their money settles at once, while a demo account is virtual USD that reaches no venue at all, on any environment where your demo switch is ON.

On the development environment:

• A partner flagged sandbox (shown on GET /partner/v1/me) under BROKER custody has deposit notices confirmed inside the POST and withdrawal requests approved and paid inside the POST, with the decision note "sandbox partner: instant settlement", so a full money round trip needs no finance action. The webhooks fire exactly as they would in production, in the same order. The flag can only be set on the development environment (revision 3): a partner record on the production environment never carries it, so the production money path always waits for our finance desk.
• A PARTNER-custody partner's collateral reports are booked at once in every environment and its settlement items are produced by the same ledger hook as in production; the sandbox flag changes nothing for it. The development venue's fills, funding and barrier events produce real settlement items, so a settlement integration can be exercised end to end (the interfirm records are written by our finance on request).
• Everything else runs the production code path: reliance must be approved by our compliance function in the back office, our screening runs (a sanctions list of test names), the MiFID assessment is scored by the same rules, orders and RFQs reach the development venue. The development venue has no venue-side liquidity source, so order books may be empty and RFQ quotes depend on the market makers connected to it; barrier RFQs on the development venue are usually quoted within seconds.
• The life-cycle events of section 16.4 (revision 8) fire on the development environment exactly as in production, for a sandbox partner too, and follow the development venue's fills and marks: an order that trades there delivers order.accepted and its fills, a barrier request its quotes and its end, a contract its barrier.closed, and a position the mark moves against delivers a real margin.call (then margin.close_out_started and margin.close_out_done when the equity reaches the close-out level). Because a market maker connected to the development venue quotes every barrier request within seconds, rfq.quote is the busiest event there: keep your endpoint answering and watch pending against maxPending on GET /webhook (section 16.3).
• A legal entity (section 9.7) is onboarded on the development environment with any well-formed entity data and an LEI whose ISO 17442 check digits are valid (the LEI of the worked example passes). Our registry lookup is off there, so leiStatus reads FORMAT_OK and counts as good standing: the MiFID level of a legal entity is granted on the format check alone on the development environment (where the lookup runs, a FORMAT_OK status is looked up at the grant first, 11.4). The document table of 9.7 binds the development environment exactly as production: the four groups, the register extract dated within the last 90 days, the legal-form kind and the listed-market carve-out (the list is empty there, so it never applies). The entity itself (by legal name and LEI) and every person are screened against the same sample list as a natural person: a person among kyb.persons named "Screening Testsanction" born 1970-01-01 exercises the PENDING_REVIEW path with the case naming that person.
• A categorisation request (section 11.6) is decided by our compliance officers in our back office on every environment: ask our operations team to decide a test request (name the requestId). The cooling period after an approval is our configuration (24 hours by default) on the development environment as well, so client.categorization_changed {status: "APPLIED"} follows an approval within a minute of the end of that period (our scheduler applies it; no read of yours is needed), while a rejection or a revocation delivers at once. A scoped request or one with another warning version stays PENDING until our officer records the published values or rejects it.
• The TERMS re-consent gate (section 10.5) is OFF on the development environment: gated reads false, gateFrom null and no route answers code 4035 with the TERMS sentence and {doc, currentVersion, gateFrom} there; the consent standing, the acceptance record and the client.consent_required webhook work exactly as in production (ask our operations team to publish a test version of a document to exercise the two stages).
• The key information document gate and the strict consent gate (section 4, 12.2) have no switch and run on the development environment exactly as in production: a RETAIL client's opening request on a barrier market answers 403 code 4035 with data.error "KID_REQUIRED" until the market's current document is acknowledged through POST .../consents {doc, version}, and with the sentence "The key information document for this market is not available yet, so this contract cannot be requested by retail clients." and data.currentVersion null while no document is published for the market (kid and kidStrict read null on GET /market-info then); a strict take profit request or preview answers data.error "RISK_DISCLOSURE_CONSENT_REQUIRED" while a Risk Disclosure version is registered and the client has not accepted it; over FIX both are 297=5 9110=4035 with the sentence in Text(58). The development environment's documents are placeholder PDFs published by our operations team: read the kid block of every barrier market you test and ask our operations team to publish the document of a market whose block reads null; a PROFESSIONAL client and the preview, the accept, the cancel and the early close are never gated.
• The market list (12.1): the development environment is to offer more markets than production. Once our operations team applies the set decided on 2026-09-30 (announced by notice), it adds, each perpetual with its knock-out market, HYPE-USD-PERP, DOGE-USD-PERP, ZEC-USD-PERP, NEAR-USD-PERP, TAO-USD-PERP, US500-USD-PERP ("US 500"), US100-USD-PERP ("US Tech 100"), XAG-USD-PERP ("Silver") and USDJPY-USD-PERP ("USD/JPY") and the nine -USD-KO twins. USDJPY-USD-PERP and USDJPY-USD-KO are USD-settled quanto contracts: the price is the USD/JPY rate in yen per dollar and each unit pays 1 USD per point of that rate, never converted at the live rate (unitLabel null); JPY-USD-PERP and JPY-USD-KO (1,000 JPY units) stay offered beside them. SP500-USD-PERP, SP500-USD-KO, NDX100-USD-PERP and NDX100-USD-KO then read offered false there (the two knock-out markets once the documents of US500-USD-KO and US100-USD-KO are published): a new opening order or barrier request answers 400 code 4000 "This market is not currently offered.", while a reducing or closing order, the early close and every read of existing exposure keep working. Read GET /instruments and offered on GET /market-info; never hard-code the list. A RETAIL client's opening request on a new knock-out market needs that market's key information document like any other (the bullet above).
• The crypto-asset risk declaration (9.2, revision 10): the development environment's cut-over date is 2026-10-15 (00:00 UTC); until then a package without crypto_asset_risk_acknowledged is accepted there, after it the key is required exactly as on production, whose cut-over date we announce with the revision 10 notice.
• The questionnaire version (11.2 and 11.3, revision 15, the code in revision 17): the development environment's cut-over date for version REQUIRED as a JSON integer on POST .../appropriateness and on POST .../appropriateness/acknowledge is 2026-11-01 (00:00 UTC); on production the requirement holds from its first day. Until that instant an absent or malformed version is scored as absent on the development environment, as 11.2 says. The same date is the development environment's cut-over for the locale and textHash requirement of 11.2 (section 21 item (2)): no questionnaire version is served in a second language there before it.
• Rehearse the stale questionnaire path (11.2) by posting version: 0: it answers 409 code 4092 with data.currentVersion and writes nothing, so your re-read and re-render path can be exercised on any client at any time without spending an attempt.
• Rehearse the whole announcement path (11.1, 16.4; revision 17) with a REHEARSAL COPY: on request our operations publish a copy of the version in force some minutes ahead (next.changeClass REHEARSAL, next.rehearsal true, renderingChanged false, nothing a client sees changes); every sandbox partner with an active webhook sees it: the ANNOUNCED event, the announced version on ?version=, then IN_FORCE under a new number. Version numbers on the development environment therefore run ahead of production: never hard code one. A submission of the copy's predecessor inside its acceptance answers the scoring-only shape of 11.2 (version the copy, submittedVersion the number you sent), because the rendering is identical.
• Sample deliveries (16.1; revision 17): POST /webhook/test with {event, stage} or {event, kind} delivers a SAMPLE of either questionnaire event to your endpoint at any time, on every environment, with data.sample true (data.sample: true; a real delivery carries no such member). A sample's version may name no real version (the ANNOUNCED sample announces the version in force plus one, some days ahead), while its read always answers: it names the version in force. A text_changed sample names the pseudo locale qps (below), never a real language.
• The pseudo locale qps (11.1; revision 17, the development environment only): GET /appropriateness-test?locale=qps serves the English text with every string wrapped [!! ... !!] and its own textHash, and a submission with locale: "qps" and that hash is scored and recorded under qps, so the whole language path, the required locale and textHash included, can be exercised end to end while the environment serves English only. It is never listed in availableLocales, never counts as a second language, and is not available on production: there a read with ?locale=qps answers the English with localeFallback true and a submission with locale qps answers 400 APPROPRIATENESS_LOCALE_NOT_AVAILABLE, exactly like any language we do not serve. Since revision 18 the same holds on the texts read (11.7): GET /texts?family=DECLARATIONS_MIFID&locale=qps serves every sentence wrapped with its own textHash, and declarationsMifidText {locale: "qps", textHash} is accepted and recorded under qps on the development environment; a text_changed sample with family DECLARATIONS_MIFID names it.
• Test cards, test identities and test money: use any well-formed data; nothing on the development environment is real money. Do not use real personal data of real persons on the development environment.
• A test screening hit: onboard a client named "Screening Testsanction" born 1970-01-01 to exercise the PENDING_REVIEW path when the sample screening list is installed.
• Rate limits and idempotency behave exactly as in production.
• The app order commands (revision 21, section 22): the development environment's audience is https://dev.brokerage.perpetuals.com/app, set in our router's configuration (empty on a host that serves no app order command, where every /app/ path answers 404). Our own partner simulator SBSIM walks the whole path there with a development key set that our edge host serves at https://dev.brokerage.perpetuals.com/dev/jwks/{name}.json (every key id of such a set starts dev-, which a production router refuses outright) and tokens minted by a tool of ours; your own issuer and key set URL are configured for you by our operations under four eyes like on production, and your web app origins are listed at our edge (22.5). The development key set path is ours alone: publish your keys at your own https URL.

19. Changelog

20. FIX gateway

Since revision 9 a partner can trade over FIX 4.4 beside these routes and the webhooks: a FIX acceptor runs inside the Order Router on its own TCP port over TLS (its own publicly trusted certificate, the same hostname as these routes; dev.brokerage.perpetuals.com:9850 on the development environment, the production endpoint told at onboarding), with no proxy in between, so your partner CIDR allowlist applies to the address the router sees. A session logs on with a TRADE key (Username(553) = the key's prefix, Password(554) = the key), one live session per key, at most four per partner, SenderCompID(49) = your partner code, TargetCompID(56) = BARRIERS; every business message names the end client with the standard Parties component (your partnerClientRef or our client uid). The gateway keeps no message store: recovery after any disconnect is the reads of section 12 plus the webhooks of section 16.

The rules of engagement, tag by tag, are docs/14-partner-fix-gateway.md: the session layer, the client attribution, order entry (NewOrderSingle, OrderCancelRequest, OrderStatusRequest; Cancel/Replace is refused), the ExecutionReport stream, the drop-copy session, the delivery semantics, the reject doctrine and the reply policy, what FIX does not carry, the conformance checklist and the custom tag dictionary (9101 to 9199). The rule that binds the transports: FIX answers with the SAME functions, sentences and codes as these routes (the code in tag 9110): a 35=D goes through the pipeline of POST .../orders with every pre-trade check of 12.3 unchanged, its ClOrdID(11) is the order's Idempotency-Key (section 5), and the ExecutionReports are produced at the SAME hook sites as the order.* events of 16.4, carrying the event's source_ref in tag 9115 and the trade id in 9111, so REST, the webhooks and FIX never disagree about a fact and a partner running two of them dedupes on that reference. An order entered over FIX reads channel: "FIX", channelKeyId and channelRef on the records of 12.3. The barrier lifecycle of 12.2 rides the same way (docs/14 section 7): a QuoteRequest(35=R) goes through the function of POST .../rfq (or, naming a contract, of POST .../barriers/{contractId}/close) with every gate and sentence unchanged, its QuoteReqID(131) is the request's Idempotency-Key and its channelRef, a QuoteResponse(35=AJ) and a QuoteCancel(35=Z) run the accept and the cancel, and the QuoteStatusReport(35=AI), the Quote(35=S) and the two contract ExecutionReport(35=8) (the open or the early-close trade, and the end for any reason) are produced at the SAME hook sites as the rfq.* and barrier.closed events of 16.4, with the event's source_ref in tag 9115. GET /me fix (section 8) confirms the gateway from your side. Since revision 21 an order your app placed with an app order command (section 22) reports to your drop-copy sessions only (it has no session key), with 9121=APP and without ClOrdID(11), because its channelRef is the token's jti; and a partner whose server-side order entry is CLOSED (22.10) is answered 9110=4043 on a NewOrderSingle(35=D) and an OrderCancelRequest(35=F) (docs/14 revision 12). Since revision 26 the conditional limit band of 12.3 refuses a NewOrderSingle(35=D) 40=4 whose Price(44) lies outside the market's band around its StopPx(99) (or around the mark once the mark has reached it) with the gateway-built 150=8 103=99 9110=4000 and the sentence in Text(58) (docs/14 revision 15). FIX carries no perpetual demo (revision 28, section 23): there is no demo message, a demo order is never reported on a session or a drop copy, and a demo event of 23.9 never reaches FIX; the demo is the REST routes of section 23 alone.

21. Compatibility and change notice

Since revision 15 (2026-09-21). This section writes down the rule this reference has followed since revision 9: revisions 9, 10 and 11 added response members, events and data.error values "additively", and the catalogue of 16.4 said of event names alone that a partner must ignore the ones it does not handle. The rule below is the codification of that practice, not a new duty, and it binds both sides from now on.

Kinds of change and their notice.

• ADDITIVE changes ship at any time with a changelog row (section 19): a new route, a new optional request member or query parameter, a new response member, a new event, or a new value of data.error, stage, status, kind or a later discriminator of the same kind. A partner MUST ignore members it does not know, event names it does not handle and values it does not know, as it has had to since revision 9. A RELAXATION (a request formerly refused is accepted, or a duty of yours withdrawn) is treated as additive.
• A TIGHTENING (a request formerly accepted is refused, a member becomes required, a value formerly ignored is validated), whether by a code change or by content we publish, is ANNOUNCED in this reference at least 30 days ahead with a cut over date per environment that has live integrations; an environment that opens later is strict from its first day. The tightenings announced under this rule, each with its cut over date: (1) version required as a JSON integer on POST .../appropriateness and on POST .../appropriateness/acknowledge (announced in revision 15, the code in revision 17; 11.2 and 11.3: production from its first day, the development environment from 2026-11-01 00:00 UTC); (2) locale and textHash required on the same two routes for every questionnaire version that is or ever was served in more than one language, and whenever the locale sent is not en (revision 17, 11.2; the requirement follows the CONTENT: production from its first day, and on the development environment no version is served in a second language before 2026-11-01 00:00 UTC, so the requirement cannot meet a partner there before that instant; send both always and it never meets you at all); (3) the members and query parameters that had no meaning before revision 17 (locale and version on GET /appropriateness-test; locale, textHash, clientLanguage and languageElection on the two writes) are VALIDATED from the deployment of revision 17: before it they were ignored, from it a malformed value is refused (a locale that is no language tag 400 LOCALE_MALFORMED, a version that is no positive integer 400, a textHash that is no sha256: hash 400), which this section's own definition makes a tightening (a request formerly accepted is refused); it ships with the code because a value a build already sends is what its platform gives it, a language tag or an integer, and the rehearsal checklist of docs/12 10.6 asks every partner whether its build sends any of them today. The precedent is the crypto-asset risk declaration of revision 10 (9.2, section 18); (4) the two members of declarationsMifidText on PUT .../mifid (11.4) had no meaning before revision 18 and are VALIDATED from its deployment (a locale that is no language tag, a textHash that is no sha256: hash or that names no text we served: a field of the route's validation map; the same class as item (3), a value a build already sends is what its platform gives it, and the rehearsal checklist of docs/12 10.6 asks); (5) declarationsMifidText.locale and .textHash REQUIRED on PUT .../mifid by content exactly like item (2): once the family DECLARATIONS_MIFID is or ever was served in more than one language, and whenever the locale sent is not en (revision 18, 11.4; production from its first day, and on the development environment no family is served in a second language before 2026-11-01 00:00 UTC, so the requirement cannot meet a partner there before that instant; send both always and it never meets you at all).
• BREAKING changes (a member removed or retyped, a meaning changed) are never made on /partner/v1: they need /partner/v2 with an overlap of at least six months in which both versions are served.
• The CORRECTION OF A DEFECT that undermines a regulatory control ships at once, with a changelog row that carries a "what to change on your side" sentence (revision 14 is the kind).
• CONTENT we publish (the questionnaire, the consent documents, the key information documents, the served sentences) follows the notice rule stated in its own section; where a section states none yet, the content is in force at its publication (the questionnaire's rule is stated in 11.1 since revision 17: a version that changes what you render is announced ahead, the read and the event carry the schedule; until the code of revision 17 is deployed on an environment you use, we will not publish a new questionnaire version on it without telling you directly beforehand, the commitment of 11.1, in force since 2026-09-22 and ending on each environment with that deployment).

The notice figures. The floor for a tightening or for a change to a content a partner renders is 14 calendar days; the practice is 30 days. An URGENT change (a regulator's instruction, a defect in a question or in the scoring, a defect that undermines a regulatory control) may be shorter and carries its reason in the changelog row; a refusal that follows from it still costs the client nothing under the attempts rule of section 11.

The questionnaire's cadence (revision 15). There is no fixed schedule for a change of the questionnaire, the warning or the acknowledgement sentence. Our compliance function reviews the questionnaire at least once a year and on product events (a product feature the knowledge questions must cover, regulatory guidance), and a change is made only when a review requires one; expect a small number of versions a year. One change is decided today and will be the first one published under the announcement mechanism of revision 17 (11.1): an additional knowledge question on the strict take profit contract variant with the scoring adjusted to it.

The channels. For your systems the channels of record are the reads of this API, the webhook events of section 16 and the changelog of section 19, read from the reference page at /docs (the OpenAPI document at /openapi.json follows at the next router deployment; the changelog row says so when they differ). For your people, until a retained notice mail to the compliance and technical contacts you register with us exists (a later revision), a direct notice given to you by a person of ours is filed on our side against your partner record. A shared chat channel is a courtesy a person may run beside these; it is never the notice of record. We ask every partner for a compliance and a technical contact so that the notice mail reaches them from its first revision.

What a partner must tolerate (the other half of the additive rule): unknown members on any answer or event; unknown data.error values on a refusal (act on code and, where you know it, data.error, never on the sentence in msg, which may be reworded); unknown event names on the webhook (the default branch answers 200); unknown stage, status, kind and family values (treat them as "a state you do not handle", never as an error); and a version of the questionnaire that is higher than the one you rendered (re-read and re-render, 11.1).

Applied to revision 16 (2026-09-22). The withdrawal of the duty to display the retail risk warning (section 8) is a RELAXATION: additive under this section, no notice period, a changelog row (section 19). The eight riskWarning members stay served with their shape and meaning unchanged, marked deprecated in this reference and in the OpenAPI document (deprecated: true and a description string on each member; no change of shape: no schema, route, field, enum value, code or event moved); their REMOVAL is a breaking change and waits for /partner/v2 with the overlap above. A partner that stops rendering them changes nothing on our side and owes us no notice. Should a barrier-specific risk sentence set later be served here and required of you, the serving is additive and the requirement a tightening announced under this section.

Applied to revision 17 (2026-09-23). The schedule members, the locale members, the two events, the query parameters and the sample body are ADDITIVE (a partner that ignores them is untouched). Three TIGHTENINGS ride with it, each listed above with its date: version required (item (1), announced in revision 15, its notice period served), locale and textHash required by content (item (2), a requirement no partner can meet before the development environment's date and that production carries from its first day), and the validation of the members and parameters that had no meaning before (item (3), from the deployment; a well formed value is never refused). Nothing is removed, retyped or given another meaning; the RESERVED members (languageElection, failText, failure, the 4035 label LANGUAGE_ELECTION_REQUIRED) promise nothing until a later revision defines them under this section.

Applied to revision 18 (2026-09-23). Every item is ADDITIVE: a new route (GET /texts, 11.7), a new optional request member (declarationsMifidText on 11.4), new response members (declarationsText on 11.4's 200 and on 11.5), new data.error values (TEXT_FAMILY_UNKNOWN and the five DECLARATIONS_* labels), a new family value of text_changed, a new family member of POST /webhook/test, a new data.error member on the 400 of 11.4. Two items are stated under the tightening rule with their dates, items (4) and (5) above, because this section's own definition makes them one. The CONTENT rule applies to the declaration sentences as 11.4 states it: a served sentence may change at any instant by an approval of our compliance function, the read is the truth and the event the signal. Nothing is removed, retyped or given another meaning.

Applied to revision 21 (2026-10-13). Every item is ADDITIVE: a new route family outside the Partner API (/app/v1, section 22, used only by a partner our operations switch ON), a new response member (appOrders on GET /me), a new value of channel on the order records (APP), a new value of 9121 over FIX (APP) and a new code (4043, never served while your server-side order entry is ALLOWED, the default). Nothing changes for a partner whose app orders are OFF. ONE TIGHTENING is announced as POSSIBLE under this section, with no date set: our operations may close a partner's server-side order entry (22.10), after which its POST .../orders, DELETE .../orders/{orderId}, PUT and POST .../leverage and its FIX 35=D and 35=F are refused with code 4043 and its clients' orders are entered through the app order commands alone. It is set only on our compliance function's decision, per partner, and announced to that partner at least 30 days ahead with its date per environment, under the notice rule above; it is never set without that notice. The token profile of 22.3, the key set rules of 22.4 and the limits of 22.9 are the agreed terms of the channel; a change to them that refuses a token formerly accepted is a tightening too.

Applied to revision 26 (2026-10-20). The conditional limit band of 12.3 refuses a request formerly accepted (a STOP_LIMIT or TAKE_PROFIT_LIMIT whose limit lies outside the market's band around the price at which it becomes a limit order, a conditional limit order of any kind without a fresh mark on a market that publishes a band, an attach leg whose limit lies outside the band around its trigger). It ships at once as the CORRECTION OF A DEFECT that undermines a regulatory control: the price check before an order reaches the venue, which the venue applies to a plain limit order and leaves to us for a conditional one; a triggered limit order of a client could otherwise trade far from the market or sweep the book. WHAT TO CHANGE ON YOUR SIDE: derive the limit of a conditional order from its trigger price and the market's priceBandBps (GET /market-info) at run time and keep it inside that band; treat the 400 code 4000 (4001 on a replace) as a refusal to show your user, never retry it unchanged. Nothing is removed, retyped or given another meaning; no code is new.

Applied to revision 27 (2026-10-21). volume24h on GET /ticker and GET /tickers reads null where it carried a figure (12.1). The figure was the traded base quantity of every trade since the venue's gateway process last started, not the 24 hour volume the member names. Before this revision the member was a string on every answer of both routes, never null (a market whose venue ticker failed carried the volume summed from the 1 hour candles), and the OpenAPI document typed it string; it now types it string or null. Under this section's own definition that is a retyping, a BREAKING change. It ships on /partner/v1 as an EXCEPTION to that rule, decided by our operator on 2026-10-26, and is in force at the publication of this revision: nothing is live and no partner has gone live. WHAT TO CHANGE ON YOUR SIDE: read volume24h as nullable and show no base 24 hour volume while it is null; read the traded value of the last 24 hours from quoteVolume24h on GET /tickers, which is null while no candle of that window could be read for the market. The OpenAPI type of quoteVolume24h, string or null, states what the router has always served; it is no change on the wire. Nothing is removed and no code is new.

22. App order commands

Since revision 21 (2026-10-13; issue #58, the design SwissBorg chose on 2026-10-09 and the profile it confirmed on 2026-10-13). The code is AppJwt.cs (the token), AppJwks.cs (your key set as we cache it), AppOrderIssuers.cs (the issuers we know), AppOrderAuth.cs (the authentication of every request), AppOrders.cs (the four routes), AppOrderCommands.cs (the record) and PartnerAppSettings.cs (your settings and the server-side switch). The walk-through for your engineers is docs/12 section 12.

An APP ORDER COMMAND is a request your app (iOS, Android or a web app in a browser) sends to us DIRECTLY when the signed-in user places, replaces or cancels a perpetual order or changes the leverage of a perpetual market. Each request carries a short-lived token your backend signed for that user and that command; nothing else of your integration passes through it. We verify the token against the key set you publish, read the client from its sub, and run the command through the SAME pipeline as the Partner API route it mirrors (12.3): every pre-trade check, gate, sentence and code is unchanged. Everything else (onboarding, KYC, MiFID, money, every read, barriers, staking, spot) stays on the Partner API, server to server, and the order life cycle reaches your backend through the order.* webhooks (16.4) exactly as for any order.

Your partner record is switched for this channel by our operations (22.2). While it is OFF, the default, nothing of this section applies to you.

The app order commands carry no perpetual demo (revision 28, section 23): the four routes place, replace and cancel live orders and change the live leverage alone, a token never reaches a demo account, and the demo is served to your backend, server to server, under /partner/v1 only.

22.1 What the token proves, and what it does not

A token that verifies under your published key proves that YOUR SIGNING KEY signed, for the client it names, within its lifetime, a statement that the command may be sent. It does NOT prove that the user entered the order, what the screen showed, or that your app (rather than your backend, or anyone holding your signing key) sent the request: a party holding your signing key can mint a token for any of your clients. Therefore:

• Mint a token only after the user authenticated in your app, only for that user, and only for that user's own command; keep the signing key in your key management system, never in the app. The partner agreement carries this as your warranty.
• We record every command with its token (22.11), so a disputed command is matched against your record of the tokens you issued by its jti.
• A token signed for a client that is NOT yours is refused and opens a case with our operations at once (22.6): your signing key produced it.
• If a key is compromised, tell our operations: one key id is blocked at once (the deny list of 22.4) without stopping the channel, or the whole channel is switched OFF (22.2).
• The token does not cover the request's content (the method, the path, the body): within its lifetime a captured token can be presented with another command for the same client. The lifetime of 22.3 is short for that reason; whether the token must also sign the request is an open question of our compliance function and would be announced under section 21.

22.2 Your settings

Our operations configure, under four eyes (one ADMIN login requests, a different ADMIN or a COMPLIANCE login approves, within 72 hours):

Switching OFF is immediate (one ADMIN act with a reason, no second login), and so is the deny list of key ids (22.4). The settings and our last fetch of your key set read on GET /me as appOrders (section 8); nothing is written through this API. The AUDIENCE is ours, one per environment, the same for every partner: https://dev.brokerage.perpetuals.com/app on the development environment; production's is told at onboarding. A host whose audience is not configured serves no app order command at all.

22.3 The token

A compact JWS (three base64url segments without padding, at most 8,192 characters), sent as Authorization: Bearer <token> on every request.

The protected header holds alg and kid, and at most typ (any value); nothing else. A header that names a key or a key location (jwk, jku, x5u, x5c, x5t), or carries crit, zip or b64, is refused: a key is never taken from the token. kid is 1 to 128 printable ASCII characters and names a key of your published set. alg is one of the algorithms agreed for you (ES256 unless agreed otherwise); none and every HMAC algorithm are refused. An ES256 signature is the 64-byte r||s form of JOSE (what WebCrypto and the JOSE libraries produce), never DER.

The claims are EXACTLY these six, and nbf when you send it; any other claim is refused, so no personal data beyond our client uid travels with a command:

We allow 60 seconds of clock skew either way: a token is refused once our clock passes exp plus 60 seconds, and before iat minus 60 seconds. Run your signing hosts on a synchronised clock. A token may carry several commands within its life (a user who places an order and moves its stop loss a minute later needs no second token), each with its own Idempotency-Key; the jti is recorded with every command it carried.

An example, decoded (the signature omitted):

{"alg": "ES256", "kid": "2026-10-a", "typ": "JWT"}
{"iss": "https://id.neobroker.example", "aud": "https://dev.brokerage.perpetuals.com/app", "sub": "BARR-00000412", "iat": 1791374400, "exp": 1791374700, "jti": "q8Hk2v0LJ3mZr7tYw1Xa"}

22.4 Your key set and its rotation

Publish your PUBLIC keys as a JSON Web Key Set ({"keys": [...]}) at the https URL of your settings. We fetch it ourselves; it never travels in a request.

• Each key carries a kid. For ES256: kty EC, crv P-256, x and y; for RS256 or PS256: kty RSA, n and e, 2,048 to 4,096 bits. A key's alg, when present, must name the algorithm it is used with; use, when present, is sig. A key of another type, curve or use is skipped.
• The whole set is refused (we keep the last good one, below) when it is not such a JSON object, holds more than 32 keys, repeats a kid, holds a malformed key or a key outside the size bounds, holds a PRIVATE member (d, p, q, dp, dq, qi, oth, k), or has no usable key. The body is read up to 64 KiB (a larger one is refused, never truncated), within 10 seconds, with no redirect followed.
• We refresh the set every 10 minutes in the background. A token naming a kid we do not hold triggers ONE immediate refetch, at most once a minute for you (never once per key id); within that minute the token is refused like any unknown key id, or answered 503 with Retry-After while the refetch is still running.
• A refetch that fails keeps the last good set in use and is shown as appOrders.lastError on GET /me; once the last good set is older than 4 hours every command is answered 503 code 5030 until a fetch succeeds.
• ROTATION, the agreed term: publish a new key at least 15 minutes BEFORE your first token signed with it (our refresh then holds it), and keep the old key in the set until the last token signed with it has expired (5 minutes plus our 60 seconds of skew after you stopped signing with it). Removing a key from the set stops it at our next fetch.
• Every key we ever fetched from you is archived with its first and last sighting, so a disputed token can be verified again after the key left your set.
• A key id beginning dev- is a development key: a production host never accepts it, and refuses your whole set while it holds one.
• The DENY LIST: on your word, or on its own judgment, our operations block one or more key ids at once (at most 32); a blocked key id is refused before any verification while the rest of the set keeps working.

22.5 The host, the edge and CORS

The four routes are served on the edge host of section 2 under /app/v1 (https://dev.brokerage.perpetuals.com/app/v1/... on the development environment), over TLS, and only there: the router behind it answers nothing under /app/ that did not come through our edge (a 404 without a body, a CORS preflight included: CORS on /app/ is the edge's alone). The edge forwards POST, PUT and DELETE under /app/ and answers the CORS preflight itself (below); every other verb (an OPTIONS that is not a preflight included) and every other path under /app/ answers 404 ({code: 4004, msg: "Not found."} from the edge, or a 404 without a body from the router). A request body is capped at 64 KiB (413 code 4130 "The request body exceeds the 64 KB limit."), and a Cookie header is dropped: the app authenticates with its token alone.

For a WEB APP, our edge answers the browser's CORS preflight itself, for the exact https origins you name to our operations (one or more, https://host or https://host:port, no wildcard, no path): a preflight from a listed origin answers 204 with Access-Control-Allow-Origin (the origin), Access-Control-Allow-Methods: POST, PUT, DELETE, Access-Control-Allow-Headers: Authorization, Content-Type, Idempotency-Key and Access-Control-Max-Age: 600; every answer to a listed origin carries Access-Control-Allow-Origin and Access-Control-Expose-Headers: Retry-After, WWW-Authenticate, and every answer Vary: Origin. Credentials (cookies) are never allowed. A preflight from any other origin answers 204 without those headers, so the browser refuses the request. The native apps send no preflight and need no origin.

22.6 The answers every route can give

Every answer is in the envelope of section 4 and carries Cache-Control: no-store.

On a 401 your app fetches a fresh token from your backend and sends the SAME request again with the SAME Idempotency-Key: nothing was executed or stored under the key (22.7). On a 429 or a 503 it waits Retry-After and does the same.

A token whose signature verified under your key but which we refuse for what it says (a sub that is not your client, a wrong aud, a lifetime above 5 minutes, an unagreed claim, your app orders OFF, your partner record stopped) is recorded as a SIGNED REFUSAL with the token (22.11); an expired or not yet valid token is not (an app holding a token past its 5 minutes is the ordinary case). A signed token for a client that is NOT yours opens a case with our operations at once: your signing key produced it. A token that fails before its signature verified is never recorded and never opens a case: anyone can send one.

A client who CANNOT TRADE is answered 403 on the place and on the replace (never on the cancel, which stays open to every client, nor on the leverage change), with the pipeline's own sentence: 403 code 4030 when the client's verification does not allow the market (the MiFID level missing, data.missingBlocks), 403 code 4035 for the consent gates, 403 code 4041 while your clients are close-only under the settlement tier (15.7), and 403 code 4044 TRADING_RESTRICTED (data.error) for a client restriction (frozen, new orders disabled on the market, close-only), a trading halt in scope, an account that is not active for trading and a legal-entity account (perpetuals are not yet open to legal entities, section 9.7) (the Partner API's own routes answer those with 400 code 4000 and the same sentence). On a replace each of these 403s means NOTHING changed, the old order stands, and its data carries cancelled: false beside the code's own members.

22.7 Idempotency

The Idempotency-Key header is REQUIRED on all four routes: exactly one, 1 to 128 printable ASCII characters without spaces (the characters ! to ~). Absent: 400 code 4000 "Idempotency-Key is required."; malformed (a space, a character outside that range, more than 128 characters, two headers): 400 code 4000 "The Idempotency-Key header must be 1 to 128 printable ASCII characters.".

• The key is SCOPED TO THE CLIENT the token names: two users' equal keys never meet. Mint one per user action (a tap on Buy), keep it with the pending action, and reuse it only for a retry of that same action.
• It is looked at only AFTER the token was accepted: a 401, a 403 4037, a 429 or a 503 of 22.6 uses nothing under the key, so the retry with a fresh token runs as a first attempt.
• The answers of the checks made BEFORE the command are NOT stored under the key either: a missing or malformed key (above), a body over 64 KiB (413 code 4130 from our edge), a body not sent as application/json (415 code 4000) and a body that is not JSON of the route's shape (400 code 4000 "The request body is not valid JSON for this command."). Correct the request and send it again with the SAME key: it runs as a first use.
• EVERY ANSWER FROM THE COMMAND ONWARD is stored and replayed BYTE FOR BYTE for 24 hours, whatever it was (a market of another family, an unknown order, every refusal of the pipeline, the 403s of a client who cannot trade, a 409, a success, a pending answer), apart from the 502 and the 503 of a failure of ours before the venue was asked (the last point below). The same key on ANOTHER request (another route, another path, another body: we compare the method, the route, the order id of the path and the SHA-256 of the body bytes) answers 409 code 4092 "This Idempotency-Key was already used for another request.". Retry with the identical body; a corrected command after a stored refusal is a new command with a NEW key.
• Two requests with the same key in flight: the second waits up to 5 seconds for the first one's answer and replays it, else answers 409 code 4092 "A request with this Idempotency-Key is still in progress."; retry with the same key a little later.
• THE POINT OF NO RETURN (section 5, revision 19): once a command may have reached the trading venue its key is never given back; for a cancel and a replace that point is the moment we ask the venue to cancel. When our side fails after that point, a lost answer of the venue call itself included (and since revision 23 the venue's answer that it could not confirm the cancel), the command answers its pending answer, stored and replayed under the key, never 502 code 5020: a place 200 with state SENT; a cancel 200 {orderId, clOrdId, pending: true}; a replace 200 {orderId: null, clOrdId: null, state: null, cancelledOrderId, pending: true}. Read the orders back (from your backend, 12.3) for the outcome; never send the command again under a new key before you did. BEFORE that point a failure of ours uses nothing under the key: 502 code 5020 (the venue could not be reached, nothing was sent) and 503 code 5030 (our store) are not stored, and the same request with the same key runs as a first attempt.

22.8 The four routes

The body is JSON (Content-Type: application/json, else 415 code 4000 "The request body must be sent as application/json."; a body that is not JSON of the route's shape answers 400 code 4000 "The request body is not valid JSON for this command."). An order id in a path is our numeric order id (4185) or its reference (BARR-4185). The ORDER routes take PERPETUAL markets only: a symbol of any other family (spot, barrier and staking included) answers 400 code 4000 "This market cannot be traded from the app." before anything is checked or written; a symbol we do not offer keeps the pipeline's own answer.

POST /app/v1/orders: a new order for the client of the token. The body is the body of POST .../clients/{clientId}/orders (12.3: symbol, side, type, qty, price, tif, reduceOnly, trigger, attach, ocoGroup, leverage) and so is the answer, byte for byte: (bare) {orderId, clOrdId, state} on acceptance, 400 {code: 4000, msg, error, orderId, clOrdId, state} on a refusal, 403 4030, 4035 or 4041, 409 code 4091 {leverageSent, leverageStored}, 502 code 5020; the ONE difference is the account that cannot open new risk (22.6), 403 code 4044 {code: 4044, msg, error, data: {error: "TRADING_RESTRICTED"}, orderId, clOrdId, state} (the shape of the 4041) where the Partner API's route answers 400 code 4000. A stop loss and a take profit are attach {takeProfit, stopLoss} on a LIMIT or MARKET entry, or later reduce-only STOP_MARKET / STOP_LIMIT and TAKE_PROFIT_MARKET / TAKE_PROFIT_LIMIT legs paired by ocoGroup; MOVING one is a replace of that leg, removing one a cancel.

POST /app/v1/orders
Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6IjIwMjYtMTAtYSIsInR5cCI6IkpXVCJ9...
Idempotency-Key: 6f1d2c4e-buy-1
Content-Type: application/json

{"symbol": "BTC-USD-PERP", "side": "BUY", "type": "LIMIT", "qty": "0.01", "price": "60000", "tif": "GTC",
 "attach": {"takeProfit": {"price": "63000"}, "stopLoss": {"price": "58500"}}}

200 {"orderId": 4185, "clOrdId": "BARR-4185", "state": "ACKED"}

DELETE /app/v1/orders/{orderId}: cancels any order of the client, by whatever channel it was placed (the app, your backend, FIX, a leg). (bare) 200 {orderId, clOrdId} when the venue accepted the cancel, or when the order was already being cancelled; 404 code 4004 for an order that is not this client's or does not exist; 400 code 4000 with the pipeline's sentence for an order that has ended or was not at the venue yet, or that the venue refused to cancel. Once the venue was asked to cancel, a failure on our side (a lost answer of the venue included) is never "nothing changed": the answer is the pending answer of 22.7, (bare) 200 {orderId, clOrdId, pending: true}, stored and replayed under the key; the venue may have cancelled the order, so read it back through your backend before anything else. The outcome reaches your webhook as order.canceled.

POST /app/v1/orders/{orderId}/replace: a CHANGE of an order is a cancel of it and a NEW order (there is no amendment in place at the venue, so the new order has a new id and loses the old one's queue position). The body is a place body (the new order, 12.3). The new order is checked in two halves, around the cancel:

• BEFORE the cancel, with the old order still standing: its shape (side, type, time in force, quantity, price, trigger), the price and lot grid, the conditional limit band of 12.3 (revision 26: a STOP_LIMIT or TAKE_PROFIT_LIMIT whose limit lies outside the market's band around its trigger price, or around the mark once the mark has reached the trigger, 400 code 4000 on the place and 4001 here, never a 403), the OCO group, the attach, the market (offered, of a family the pipeline trades, not disabled for new risk), the account's gates (the verification gate, the client's restrictions and the trading halts, the consent gates, your clients' close-only state, an account not active for trading) and the leverage hint. A refusal here CHANGES NOTHING: 400 code 4001, a 403 of 22.6, or 409 code 4091.
• AFTER the cancel, because they need the old order out of the picture: the reduce-only check (a reduce-only new order must reduce the open position: "This reduce-only order is larger than your open position, so it cannot be placed.", "There is no open position on this market for a reduce-only order to reduce.") and the margin check (the free margin, a usable mark, no close-out in progress on the account; the leverage hint once more, should the stored leverage change in between), then the venue's own answer to the new order. A refusal here is 400 code 4002: the old order IS GONE.

So moving a stop loss or a take profit (a replace of its reduce-only leg) can end with neither leg: when the position shrank below the new leg's quantity, or closed, the new leg is refused after the old one was cancelled. On a 4002 your app tells the user that the old order (the old leg) is gone and offers to place it again (a new POST /app/v1/orders under a new key); it never assumes the old order still stands.

The replacement is an order of this channel with its own jti, whatever channel placed the order it replaces.

PUT /app/v1/leverage: the user's leverage choice on one perpetual market, body {symbol, leverage}; the answer is the one of PUT .../clients/{clientId}/leverage (12.3): (bare) 200 {symbol, leverage, cap, categorization, chosen}, 400 code 4000 above the cap or not a whole number, 404 code 4004 for a market that is not offered. A change that raises the initial margin and would leave the free margin negative or the account in margin call or close-out is ALWAYS refused with 409 code 4090 and data {wouldBreach: true, initialMarginAfter, maintenanceMarginAfter, freeMarginAfter, marginLevelAfter, riskStateAfter}: the app route NEVER applies it, and a force member in the body is ignored (we keep, in our record of the command, that it was sent). The sentence of that refusal reads "At <leverage>x your open positions and orders would need <amount> USDC of initial margin and your free margin would be <amount> USDC, <the consequence>. The leverage was not changed.", the consequence being "which is more than your account holds", "which would put your account in margin call" or "which would start a close-out of your positions": the figures and the consequence of PUT .../clients/{clientId}/leverage, whose sentence ends "Confirm to apply it anyway." instead (your backend's route accepts force, the app route never does). The leverage stays as it was; the app offers no confirmation and asks the user for a lower leverage instead.

22.9 Limits

Three sliding windows of 60 seconds, in memory per router host, none of which is a Partner API window (section 6) or your FIX sessions' bucket:

Beyond a limit: 429 code 4290 "Too many requests. Please slow down and try again." with Retry-After, the whole seconds until that window admits again (at least 1). The limits are our configuration, the same for every partner of an environment; a change that lowers one is announced under section 21.

22.10 Server-side order entry

Our operations hold, per partner, whether your SERVER-SIDE order entry is ALLOWED (the default) or CLOSED. While it is CLOSED, your backend's POST .../orders, DELETE .../orders/{orderId}, PUT and POST .../leverage answer 403 code 4043 SERVER_ORDER_ENTRY_CLOSED ("Server-side order entry is closed for this partner: orders, cancels and leverage changes are entered through the app order commands.", data.error), and over FIX a NewOrderSingle(35=D) and an OrderCancelRequest(35=F) answer 9110=4043 with the same sentence (docs/14 3.4 and 3.5), before anything is looked at or stored; every read, the FIX status request, barriers, staking, money and the app order commands stay open. Whether a partner's server-side order entry must close once its app sends the commands directly is a decision of our compliance function; it is set only on that decision and announced to you at least 30 days ahead under section 21. No date is set for any partner.

22.11 The record of every command

Every command whose token we accepted, and every signed refusal (22.6), is recorded on our side in an append-only table with: the token verbatim and its SHA-256, its iss, aud, sub, kid, alg, jti, iat and exp, the Idempotency-Key, the request's fingerprint, for a leverage change its symbol and leverage, the caller's address, origin and user agent, the instant, the outcome (EXECUTED, REFUSED, REFUSED_SIGNED, REPLAY, or PENDING for a cancel or replace that failed on our side past its point of no return and was answered its pending answer, 22.7; a place whose venue answer was lost, or not confirmed by the venue (revision 23), is answered state SENT by our pipeline itself and recorded EXECUTED, the order converging through our reconciliation) with the status, the code and the sentence, the order the command placed and the order it acted on. The record is never purged: it is kept as long as the orders (the 24 hours of the Idempotency-Key store are never the record). An order the command placed reads channel APP and channelRef the jti on every read and event (12.3, 16.4); our own order history names the partner, the issuer, the key id and the jti beside it, and our audit lines say that the client placed it through your app. To dispute a command, give our operations its jti: they find every command the token carried and can verify the token again against the archived key (22.4). On a client's erasure under data protection law the address, the origin and the user agent are blanked; the token, its claims and the order links stay as the order record.

22.12 The development environment

The audience is https://dev.brokerage.perpetuals.com/app (section 18). Our partner simulator SBSIM exercises the channel end to end there with development keys (key ids dev-...) that our edge host serves at https://dev.brokerage.perpetuals.com/dev/jwks/{name}.json; those keys and that path are ours. For your integration our operations configure your own issuer and key set URL under four eyes, and list your web app origins at our edge (22.5); a key set published for the development environment may hold dev- key ids, a production one may not. The conformance list is docs/12 section 12.

23. Perpetual demo accounts

Since revision 28 (2026-10-24; issue #122, the operator's decisions of 2026-10-24). The code is PartnerDemo.cs (the routes, the switches and the webhook door), DemoPerp.cs, DemoPerp.Engine.cs, DemoPerp.Loops.cs and DemoPerp.Wire.cs (the engine) and DemoPerpMath.cs (the pure core). The walk-through for your engineers is docs/12 section 13.

A PERPETUAL DEMO ACCOUNT is a simulated perpetual futures account in VIRTUAL USD that you open for one of your clients and trade for that client from your backend, server to server, under /partner/v1/clients/{clientId}/demo/perp. Your user practises our perpetual markets with the live economics (the client's own leverage caps, margin, margin call, close-out, negative balance protection, commission and funding) and no money at risk. Your demo switch is OFF by default (23.2); while it is OFF nothing of this section applies to you.

23.1 What the demo is, and what it is not

• A demo order is NOT an order. Nothing is sent to the trading venue and nothing is executed. No order, trade, position, balance, ledger posting, statement, transaction report or settlement item of the client exists because of it, and nothing of the demo shows on a live read of section 12 or of section 15.
• The money is VIRTUAL USD (currency "USD", virtual true, whatever your custody model and collateral asset): it has no value, cannot be deposited, withdrawn, transferred or converted, and is never part of the client's real balances (the display rules are 23.10).
• The demo reads the venue's PUBLIC market data only: the mark price, the public ticker, the instrument facts, each market's trading state and the venue's funding settlements.
• DEMO FILLS ARE AT THE MARK (23.4). Live fills differ by the spread and the depth of the order book, and a live order can wait in a queue or not fill at all.
• There is NO LEAGUE: no ranking, no alias, no badge, no prize and no reward of any kind on the demo, and nothing of an account is shown to another client. A partner's client is never part of our barrier demo league either.
• Server to server only: no demo on the app order commands of section 22 (/app/v1) and none over FIX (section 20).
• No verification level is required (23.3 names who is refused). Demo activity never feeds the appropriateness assessment of section 11.
• The demo routes, objects and identifiers stay apart from the live ones: a demo route accepts only the demo's own ids (DPA-, DPO-, DPF-, DPJ- followed by digits), so an order id of section 12 answers 404 there, and a live route never binds a demo id.

23.2 The switches and the order of the checks

Every demo route decides, in this order, each before the next is looked at:

1. OUR GLOBAL DEMO SWITCH (the one that also withdraws our own clients' demo desk). While it is off every demo route answers 503 code 5030 "The demo account is not available." and no demo event is sent.
2. YOUR PARTNER SWITCH, OFF by default, switched ON or OFF by an ADMIN of our operations with a reason (a direct act, no four-eyes request: no money moves). While it is OFF every demo route answers 403 code 4047 DEMO_NOT_ENABLED "The perpetual demo is not enabled for this partner." with data {"error": "DEMO_NOT_ENABLED"}, and no demo event is sent. It is decided before the client, the Idempotency-Key and our idempotency store: nothing is stored, and the same key runs as a first use once the switch is ON.
3. THE CLIENT: a client that is not yours answers 404 code 4004 "Unknown client." before any key is claimed (section 7).
4. On a keyed write, the Idempotency-Key (23.8).
5. The route itself (23.6).

A router that does not run the demo answers 503 code 5030 "This service is not available on this router." after the global switch. GET /partner/v1/me demo.perp (section 8) shows the switches as they apply to you: enabled is your switch, available is your switch AND our global switch AND the demo running on the host you reached. On the production environment the demo is not offered before our compliance function has approved its served texts (23.10) and the go-live items of docs/12 10.6 are done; available is the truth.

The demo is NOT gated by your server-side order entry (22.10, code 4043), your reliance status (code 4036), our verification gate (4030), the TERMS, key information document and risk disclosure consent gates (4035), or the settlement close-only state of 15.7 (4041): no demo route ever answers 4030, 4035, 4036, 4041, 4043 or 4044, and 4047 is the demo's alone. The client restrictions and trading halts of our compliance function do apply (23.4).

While either switch is off the accounts stay as they are: the open positions keep their economics (resting orders fill, triggers fire, funding is charged, margin call and close-out run), you can neither read nor write them, and no event reaches you, including none for what happened meanwhile: read the account back when the demo is available again. The retention of 23.3 pauses meanwhile.

23.3 The account: opening, balance, top-up, reset, retention, deletion

• ONE ACCOUNT PER CLIENT, identifier DPA-<n>.
• OPENING: POST .../demo/perp/account with {"adultConfirmed": true}. The member is YOUR ATTESTATION that the client is 18 or older; we record it with your partner code, your key's prefix and the instant, and ask the client nothing. Without a JSON true the open answers 400 code 4000 "A demo account is available to adults only: confirm that the client is 18 or older with adultConfirmed set to true." A new account answers 201 with a balance of 10,000.00 USD; an existing one answers 200 as it stands (never a second starting balance).
• WHO IS REFUSED: a CLOSED client 409 code 4092 "This account is closed." (data.error ACCOUNT_CLOSED) on every write but the deletion; a client whose lifecycle state is not KYC_PENDING, KYC_APPROVED or ACTIVE (any state added later included), whose latest KYC package our compliance function rejected, who holds a standing sanctions match or whose latest screening result is a hit not yet decided: the open and every opening order answer 400 code 4000 "A demo account is not available for this client." Such a client keeps every read, cancels, reducing orders, top-ups, resets and the deletion. These are prudence rules, not a verification level.
• CAPACITY: at most 100,000 demo accounts on our side and 50,000 per partner; beyond either the open answers 409 code 4092 "The demo is at capacity." (data.error DEMO_AT_CAPACITY). At most 50 live orders per account: "You can have at most 50 open demo orders." (400 code 4000). An order whose attach carries a take profit and a stop loss counts as the two live orders it becomes when it fills (one leg, one), so the legs a fill creates never take the account past the cap.
• TOP-UP: POST .../demo/perp/top-up {"amount": "500.00"} adds virtual USD: a decimal string (or a JSON number) of at most two places, 1.00 to 10,000.00 a call, else "The top-up must be between 1.00 and 10,000.00 USD, in whole cents.", and at most 90,000.00 since the last reset, else "Top-ups since the last reset are capped at 90,000.00 USD; 1,500.00 USD remain." with what remains. At most 100,000 USD go into an account per reset.
• RESET: POST .../demo/perp/reset at any time, never refused for a restriction, a margin call or a close-out: every live order is cancelled (reason RESET), every position is closed WITHOUT a fill (no result is booked), the balance returns to 10,000.00 USD by one RESET journal entry, the top-ups since the last reset and the risk state are reset (NORMAL), and no funding settlement before the reset is ever charged. The leverage choices stay.
• RETENTION (30 days). Every order FILLED or CANCELED more than 30 days ago is deleted with its fills, and every journal entry older than 30 days is deleted with its amount carried into the account (the balance does not move; the journal no longer sums to it). An account without a WRITE of yours for 30 days (an open, an order, a cancel, a replace, a close, a leverage change, a top-up or a reset; a read does not count) is deleted WHOLE, open positions included, with the event demo.account.deleted {reason: "INACTIVE"}. While the demo is unavailable to you (23.2) nothing is deleted, old rows included, and the 30 days count again from the moment it is available; an account whose partner switch has stayed OFF for 90 days is deleted all the same. deleteAfter on the account is the instant after which our hourly retention deletes it: 30 days after the latest of your last write, your switch's last change and our global switch's last start, every rule above applied. A deleted account answers 404 code 4004 "This client has no demo account." (data.error NO_DEMO_ACCOUNT); open a new one if your user wants to continue.
• DELETION ON REQUEST: DELETE .../demo/perp/account deletes every row of the account at once (orders, fills, positions, leverage choices, journal and the account), is never refused for a restriction or a closed client, answers 200 {deleted: true, counts} and sends demo.account.deleted {reason: "PARTNER"}; without an account it answers 200 {deleted: false}. Use it when your user asks you to delete their demo data. Like every demo route it answers 503 or 4047 while the demo is unavailable to you (23.2): send such a request to our operations then. Our compliance function deletes on a request that reaches us directly, whatever either switch reads (reason STAFF).
• ATTRIBUTION: a demo write is recorded on the demo row it wrote (your partner code and key prefix; system for our own passes) and goes with the row; it never lands on the client's supervisory record.

23.4 The economics: the live rules, fills at the mark

Every figure comes from the SAME functions as a live account (the margin engine, the close-out state machine, the funding arithmetic and the commission arithmetic) over the demo account's own rows.

• FILLS AT THE MARK. A demo order that can fill at once (a MARKET, a LIMIT that reaches the mark, the child of a triggered conditional that does) fills its WHOLE quantity at the venue's mark price read from the venue's public ticker AT THE INSTANT OF THE FILL, never at an older mark. Every order you send that is not conditional is decided on that same read: whether it can fill at once, whether a POST_ONLY order would cross, the price band and the order's value. It fills nothing while the opposite side of the venue's order book is empty (no best ask for a buy, no best bid for a sell): a MARKET or an IOC order is then cancelled IOC_UNFILLED, a FOK order FOK_UNFILLED, and a GTC LIMIT stays OPEN as an order that WAITS FOR THAT SIDE: it never fills at its own limit while the side is empty, fills whole at the mark of the ticker our mark loop reads once the side has an order, and, once that mark has moved away from its limit, rests as any limit does. The size is never bounded by the depth of the book and the demo never moves the book. A RESTING LIMIT fills whole at ITS OWN price as soon as the mark reaches it, gap or not, without a queue. A POST_ONLY order that would cross the mark is refused (23.7). A CONDITIONAL order triggers on the mark whatever trigger.source you sent (LAST, MARK or INDEX; the order reads trigger.evaluatedOn "MARK"), from the next pass of our mark loop (about every second over marks polled every 2 seconds). LIVE FILLS DIFFER BY THE SPREAD AND THE DEPTH OF THE BOOK: a live market order pays the spread and walks the book within the venue's price collar, a live limit order waits in a queue and may never fill, and a live order meets other traders and latency. A demo result is never what the same orders would have produced live.
• liquidity on a fill is a label, TAKER for an immediate fill and MAKER for a resting limit; the commission is the same for both.
• COMMISSION: the client's own commission scheme for perpetuals (your default scheme included where it applies), its terms frozen at the order's first fill, charged on each fill's notional with the per-order minimum and rounded up to the micro, exactly as a live order is charged. A fee you charge your users yourself is not simulated.
• LEVERAGE: the client's LIVE caps, by its categorisation and the market's asset class, and the account's own choice per market (PUT .../demo/perp/leverage), bounded the same way. A demo choice never touches the client's live leverage, and a live choice never the demo's.
• MARGIN, MARGIN CALL, CLOSE-OUT, NEGATIVE BALANCE PROTECTION: the live engine with the thresholds that apply to the client (12.3) on the demo account, risk states NORMAL, MARGIN_CALL and CLOSE_OUT. On a close-out every live demo order is cancelled (CLOSE_OUT) and every position is closed at the mark, commission charged, in the pass that decides it; a position on a market the venue holds halted or in a post-only session (where the venue refuses a market order, a live close-out's included), or without a fresh ticker, is closed on a later pass. Once flat, a negative balance of a client our negative balance protection covers (RETAIL) is brought back to zero by an NBP_WRITEOFF journal entry; another client's negative balance stays until a top-up or a reset. A LIVE close-out cancels first and closes at the book's prices on a later tick, so it usually realises more loss than the demo's.
• FUNDING: charged and paid on demo positions at the venue's own funding settlements (the settlement's fundingRate and markPrice, the position held at the settlement's fold line) with the live arithmetic -round_half_even(qty x markPrice x fundingRate, 6 places): a long pays a positive rate, a short receives it. One FUNDING journal entry per settlement and account, never for a settlement before the account's open or last reset, and none where the venue settles none (a market that cannot trade). It follows the venue's records shortly after we record them. A demo account is never part of our firm's net position at the venue, so no rounding remainder (15.3) ever reaches it.
• THE VENUE'S MARKET-LEVEL RULES, with the live sentences (23.7): the price band of a LIMIT, the minimum and the maximum order value, post-only, and each market's trading state as the venue publishes it (read every 5 seconds; a state older than 30 seconds reads as trading): no fill and no trigger on a market or venue the venue holds halted or delisted; while a market is reduce-only only an order that reduces the client's position AND is a MARKET, or a LIMIT IOC or FOK, without attach is admitted (the live router sends exactly such an order again with the venue's reduce-only flag; a resting order, a conditional or an order with attach is refused, reducing or not); every order that is not post-only is refused while a market is post-only. The minimum order value applies to every order you send, the close of 23.6 included, as it does live; only the close-out's own flatten and an order a reduce-only session admitted are exempt (the venue exempts its reduce-only flag). A member-level outcome of the venue (its margin, position and order caps on our firm, its liquidation, ADL and throttles) never applies to the demo.
• A FRESH MARK is required for every demo order, a resting limit included (live accepts a resting limit on a stale mark; the demo cannot decide a fill without one): "There is no fresh mark price for SOL-USD-PERP right now. Please try again shortly."
• Every order passes the client's restrictions and our trading halts (a frozen account refuses even a reducing order, as live), the market controls of our operations, and the legal-entity rule (perpetuals are not yet open to legal entities: an opening order of a legal-entity client is refused with the live sentence; its account and reads are available). Your settlement close-only state of 15.7 is NOT applied: it concerns real money between you and us.

23.5 The routes

B stands for /partner/v1/clients/{clientId}/demo/perp; {clientId} is our numeric client id or the BARR- uid, as on every client route.

Every answer is the envelope of section 4, {"code": 0, "data": {...}}, and every data carries "demo": true; no demo route is bare. Every route but 1 and 19 answers 404 code 4004 "This client has no demo account." with data.error NO_DEMO_ACCOUNT while the client holds no account. The paged reads take limit 1 to 200 (default 50, else "The page size must be a whole number between 1 and 200.") and before, the exclusive cursor in the route's own id form (DPO-<n>, DPF-<n>, DPJ-<n>; anything else "The paging cursor is not valid."), newest first; next is the cursor of the next page or null. state filters orders (PENDING_TRIGGER, OPEN, FILLED, CANCELED), kind filters the journal (OPEN, TOP_UP, RESET, REALIZED_PNL, COMMISSION, FUNDING, NBP_WRITEOFF, RISK_STATE); another state or kind answers 400 code 4000 naming the values (23.7). symbol filters fills; a market the account never traded answers an empty page. Money is a decimal string of 6 places in virtual USD, prices and quantities decimal strings, times Unix milliseconds.

23.6 Each route

POST B/account {"adultConfirmed": true} (23.3). 201 or 200:

{
  "code": 0,
  "data": {
    "demo": true,
    "account": {
      "accountId": "DPA-41", "virtual": true, "currency": "USD",
      "balance": "10000.000000", "startingBalance": "10000.000000", "toppedUp": "0.000000", "topUpRemaining": "90000.000000", "resets": 0,
      "createdAt": 1793011200000, "resetAt": null, "lastActivityAt": 1793011200000, "deleteAfter": 1795603200000,
      "riskState": "NORMAL", "categorization": "RETAIL", "closeOutPct": "50", "marginCallPct": "100", "negativeBalanceProtection": true,
      "margin": {"equity": "10000.000000", "cash": "10000.000000", "unrealizedPnl": "0.000000", "initialMargin": "0.000000", "maintenanceMargin": "0.000000",
                 "marginCallLevel": "0.000000", "positionMargin": "0.000000", "orderMargin": "0.000000", "freeMargin": "10000.000000", "marginLevel": null,
                 "closeOutEquity": "10000.000000", "marksFresh": true},
      "positions": [],
      "openOrders": 0,
      "notice": {"version": "demo-perp-notice-1", "sha256": "7164475b22e02cde2a19329ddb3dcdef49c7e11ee44c18feb71231abf9b91638",
                 "provider": "This demo is provided by PM MTF Ltd. It is a simulation: no order is sent to any market and no money is at risk.",
                 "virtualFunds": "The balance is virtual USD. It has no value, cannot be withdrawn and is not part of your real balances.",
                 "simulated": "Simulated results do not indicate future results. Live trading can lose more quickly than a simulation suggests.",
                 "notSimulated": "Demo orders fill at the mark price. Live fills differ by the spread and the depth of the order book, and live orders can wait in a queue or not fill at all.",
                 "text": "[the four sentences above, in this order, joined by a space]", "kid": null},
      "riskWarning": {"standard": "[the standard retail risk warning as our disclosures read serves it]", "fallback": false}
    }
  }
}

The account (DemoPerpAccount): balance the virtual cash (the starting balance, the top-ups, the realised results, the commission, the funding and a write-off); startingBalance at the open or the last reset; toppedUp and topUpRemaining since the last reset; resetAt the last reset (null before one); deleteAfter the instant after which our retention deletes the account (23.3); riskState and the live facts applied (categorization, closeOutPct, marginCallPct, negativeBalanceProtection); margin the live GET .../margin figures of 12.3 for the demo account, perpetual members only (no barrier, spot or pending accept member); positions the DemoPerpPosition objects; openOrders the number of live orders; notice and riskWarning 23.10.

GET B: the account, as above.

POST B/top-up {"amount": "500.00"} (23.3): {account, entry}, entry the TOP_UP journal entry.

POST B/reset (no body, or {}; 23.3): {account, canceledOrders, closedPositions}, the two counts of what the reset cancelled and closed.

POST B/orders: the LIVE order body of 12.3, unchanged (symbol, side, type, qty, price, tif, reduceOnly, trigger, attach, ocoGroup, leverage), so your live ticket serves both. Perpetual markets only: another family answers 400 code 4000 "Demo accounts trade perpetual markets only." The checks run in the live order (the shape, the market, the restrictions and halts, the market controls, the OCO group, the grid, a fresh mark, the attached legs, the venue's market-level rules, the open order cap, the leverage hint 409 code 4091 with {leverageSent, leverageStored}, the live margin check with its sentences), and a refused order writes nothing. Then the order fills, rests (OPEN) or waits for its trigger (PENDING_TRIGGER) as 23.4 says. A filled parent with attach creates its take profit and stop loss legs as PENDING_TRIGGER reduce-only orders of origin ATTACHED in one OCO group, as live; the fill of one cancels the other (OCO); a reduce-only order the position no longer needs is resized or cancelled (REDUCE_ONLY).

{
  "code": 0,
  "data": {
    "demo": true,
    "order": {"orderId": "DPO-1207", "symbol": "SOL-USD-PERP", "side": "BUY", "type": "MARKET", "tif": "IOC", "qty": "10", "price": null, "trigger": null,
              "reduceOnly": false, "ocoGroup": null, "attach": null, "parentOrderId": null, "replacesOrderId": null, "origin": "CLIENT", "state": "FILLED",
              "filledQty": "10", "avgFillPrice": "150.25", "commission": "0.751250", "cancelReason": null, "leverage": 10,
              "createdAt": 1793011260000, "triggeredAt": null, "doneAt": 1793011260000},
    "fills": [{"fillId": "DPF-3301", "orderId": "DPO-1207", "symbol": "SOL-USD-PERP", "side": "BUY", "qty": "10", "price": "150.25", "liquidity": "TAKER",
               "mark": "150.25", "commission": "0.751250", "realizedPnl": "0.000000", "origin": "CLIENT", "ts": 1793011260000}],
    "account": {
      "accountId": "DPA-41", "virtual": true, "currency": "USD",
      "balance": "9999.248750", "startingBalance": "10000.000000", "toppedUp": "0.000000", "topUpRemaining": "90000.000000", "resets": 0,
      "createdAt": 1793011200000, "resetAt": null, "lastActivityAt": 1793011260000, "deleteAfter": 1795603260000,
      "riskState": "NORMAL", "categorization": "RETAIL", "closeOutPct": "50", "marginCallPct": "100", "negativeBalanceProtection": true,
      "margin": {"equity": "9999.248750", "cash": "9999.248750", "unrealizedPnl": "0.000000", "initialMargin": "150.250000", "maintenanceMargin": "75.125000",
                 "marginCallLevel": "150.250000", "positionMargin": "150.250000", "orderMargin": "0.000000", "freeMargin": "9848.998750", "marginLevel": "6655.07",
                 "closeOutEquity": "9999.248750", "marksFresh": true},
      "positions": [{"symbol": "SOL-USD-PERP", "side": "LONG", "netQty": "10", "avgEntryPrice": "150.25", "mark": "150.25", "markFresh": true,
                     "unrealizedPnl": "0.000000", "initialMargin": "150.250000", "roiPct": "0.00", "leverage": 10, "realizedPnl": "0.000000",
                     "estLiquidationPrice": null, "openedAt": 1793011260000, "updatedAt": 1793011260000}],
      "openOrders": 0,
      "notice": {"version": "demo-perp-notice-1", "...": "the notice of POST B/account"},
      "riskWarning": {"standard": "[the standard retail risk warning]", "fallback": false}
    }
  }
}

(Illustrative figures: a commission scheme of 5 basis points on the notional of 1,502.50 USD, and the RETAIL cap of 10 on the market.)

The order (DemoPerpOrder): the live order members of 12.3 where they apply, orderId DPO-<n>, trigger {source, price, direction, limitPrice, evaluatedOn}, attach {takeProfit, stopLoss, legs, note} (legs the DPO- ids of the legs once the parent filled), parentOrderId and replacesOrderId as DPO- ids, origin CLIENT, ATTACHED or CLOSE_OUT, state PENDING_TRIGGER, OPEN, FILLED or CANCELED, filledQty, avgFillPrice, commission, cancelReason (CLIENT, REPLACED, IOC_UNFILLED, FOK_UNFILLED, OCO, REDUCE_ONLY, CLOSE_OUT, RESET, RESTRICTION, HALT), leverage (the effective leverage at admission), createdAt, triggeredAt, doneAt. The fill (DemoPerpFill): fillId DPF-<n>, orderId, symbol, side, qty, price, liquidity, mark (the mark the fill was decided on), commission, realizedPnl, origin, ts.

DELETE B/orders/{orderId} (DPO-<n>; anything else, or an order of another account, 404 code 4004 "This demo order was not found." with data.error DEMO_ORDER_NOT_FOUND): {order} with state CANCELED, cancelReason CLIENT; an order no longer live answers 400 code 4000 "This demo order is no longer open."

POST B/orders/{orderId}/replace {"order": <the body of POST B/orders>}: ATOMIC. The old order is cancelled (REPLACED) and the new one admitted in ONE step; any refusal changes nothing (the sentence, with data {cancelled: false, placed: false}). 200 {canceled, order, fills, account}, canceled the old order, order the new one with replacesOrderId. Unlike the live replace (codes 4001 and 4002) the demo never leaves you without the old order and the new one.

GET B/orders/open: {orders}, every live order, oldest first. GET B/orders: {orders, next}. GET B/orders/{orderId}: {order, fills}.

GET B/positions: {positions, marksFresh}. The position (DemoPerpPosition): symbol, side (LONG or SHORT), netQty, avgEntryPrice, mark, markFresh, unrealizedPnl, initialMargin, roiPct, leverage, realizedPnl (since the position opened), estLiquidationPrice, openedAt, updatedAt: the live position figures of 12.3.

POST B/positions/{symbol}/close {"qty": "4"} (optional; default the whole position, at most its size: "This reduce-only order is larger than your open position, so it cannot be placed.", a quantity that is not a positive number "The quantity must be a number greater than zero."; no position "There is no open demo position on this market."): a reduce-only MARKET IOC on the opposite side through the same checks as an order, the minimum order value included (a position below it cannot be closed this way, as live: reset the account). {order, fills, account}.

GET B/fills: {fills, next}, newest first.

GET B/leverage?symbol= (a symbol is required: "A market symbol is required."): {leverage} in the live shape {symbol, leverage, cap, categorization, chosen}, cap the client's live cap, chosen the demo account's choice (null until one is set), leverage the effective one.

PUT B/leverage and POST B/leverage {symbol, leverage, force}, the live body: the choice within the live cap (the live sentences), stored on the demo account; a change that would put the account in margin call or close-out without force answers 409 code 4090 with the live data (wouldBreach, initialMarginAfter, maintenanceMarginAfter, freeMarginAfter, marginLevelAfter, riskStateAfter); leverage missing "A leverage value is required.". {leverage} as above.

POST B/margin/preview: the live preview body (symbol, side, type, tif, qty, price, trigger, reduceOnly, leverage), no side effect and no key, the live preview members on the demo account (accepted, reason, orderValue, marginRequired, leverage, freeMarginBefore, freeMarginAfter, marginLevelAfter, estLiquidationPrice, equityBefore, initialMarginBefore, initialMarginAfter, estimatedCommission, slippageAllowance, estimatedCosts).

GET B/journal: {entries, next}, every balance move of the account and every risk state change. The entry (DemoPerpJournalEntry): entryId DPJ-<n>, kind (OPEN, TOP_UP, RESET, REALIZED_PNL, COMMISSION, FUNDING, NBP_WRITEOFF, RISK_STATE), amount (signed; 0 on RISK_STATE), balanceAfter, symbol, orderId, fillId, settledAt (a FUNDING entry's settlement), detail (a FUNDING entry {qty, rate, mark, foldAt}, a RESET {balanceBefore, canceledOrders, closedPositions, riskStateBefore}, a RISK_STATE the transition and its figures), ts.

DELETE B/account (23.3): {deleted: true, counts: {journal, fills, orders, positions, leverage, account}} or {deleted: false}.

23.7 Errors

The live sentences of 12.3 travel unchanged; the demo's own:

The venue's market-level rules answer 400 code 4000 with the LIVE client sentence of the venue's code, the same one a live order gets:

A demo route never answers 4030, 4035, 4036, 4041, 4043 or 4044.

23.8 Idempotency and rate limits

• KEYED (the Idempotency-Key of section 5, optional as everywhere, the 24-hour store with the body compared): POST B/account, POST B/orders, POST B/orders/{orderId}/replace, POST B/positions/{symbol}/close, PUT B/leverage (and its POST twin), POST B/top-up and POST B/reset. NOT KEYED: DELETE B/orders/{orderId} (a repeat finds the order no longer open), DELETE B/account (a repeat answers {deleted: false}) and the preview (no side effect). A demo write never reaches the venue, so it marks no point of no return; the demo ALSO records the key on the order or journal row it wrote, so a retry after a fault of our store finds that row and answers it instead of writing a second order, top-up or reset (for 24 hours, and only for the same body; another body under the key answers 409 code 4092 "This Idempotency-Key was already used for another request.").
• RATE LIMITS: a demo request counts in the partner's DEMO windows only, two sliding 60 second windows of their own: 600 GET and HEAD requests and 120 other requests per minute, shown on GET /me demo.perp.limits. Beyond them 429 code 4290 with the live sentence. Demo traffic never draws on your live readPerMinute and tradePerMinute (section 6), your FIX bucket or the windows of the app order commands, and live traffic never on the demo's.

23.9 Webhooks: the demo events

The demo's events reach your webhook (section 16) with the live envelope, signature, retry and retention, under names of their own that all start with demo. and are never among the live names of 16.4:

• No personal data beyond the envelope's clientId, clientUid and partnerClientRef, as on the live events.
• Nothing is enqueued while either switch of 23.2 is off.
• DEMO EVENTS ARE BEST EFFORT AND MAY LAG: our worker delivers every live event of a partner ahead of rfq.quote and rfq.quote ahead of every demo event, and attempts at most 10 demo events of yours per delivery pass and none once your turn of the pass has taken 2 seconds, so demo traffic never holds back a live event of the next pass; and while 1,000 or more deliveries of yours are pending (every event counted; our setting Partners:Demo:WebhookMaxPending, never above the live cap of 16.3) a further demo event is DROPPED, not queued. The live rfq.quote cap of 16.3 counts no demo event, so demo traffic never costs you a live quote. A delivered demo event leaves our delivery log after a day (a live one after 30 days, 16.3). The account reads of 23.6 are the source of truth: re-read after a gap.
• A demo event never reaches a FIX session or a drop copy (section 20).
• Deduplicate on the envelope's id as for every event (16.2).

23.10 What you must show

THE NOTICE. Every account answer carries notice, the demo notice we serve in English, ENGLISH MASTER AND NOT YET APPROVED COPY: each sentence passes our marketing approval per language before the demo is offered on the production environment, and the version tag moves with every change of a sentence. Show the four sentences VERBATIM wherever the demo is offered, in the predominant font size of the screen, never rephrased, translated or shortened by you:

text is the four joined by a space, sha256 the lower-case hex SHA-256 of the notice's canonical text (family=DEMO_PERP_NOTICE, locale=en, then t.<member>=<sentence> per member in this order, each line ended by a line feed): 7164475b22e02cde2a19329ddb3dcdef49c7e11ee44c18feb71231abf9b91638 for version demo-perp-notice-1. kid is null: no key information document for a perpetual market is filed yet; once one is, kid carries {doc, version, url} and showing where it is becomes part of this duty. Re-read the account at least daily so a changed notice reaches your users within a day.

The notice is served in English only today. An app that shows the demo in another language agrees with us before go-live whether it shows the English notice or waits for a translation, which we serve only once our compliance function has approved it for that language (docs/12 10.6).

riskWarning is the standard retail risk warning form as our disclosures read serves it ({standard, fallback}). Whether your demo screen must show it is an open question of our compliance function (with the risk indication a marketing communication carries); until it is decided it is served for you to show. Revision 16 deprecated the same form on GET /me disclosures for the live products of this API, which the reference requires it for none of; the demo serves it beside the notice because the question for the demo is still open.

THE VIRTUAL LABEL. Every demo figure carries the word "virtual" or "demo" beside it; a demo balance, result or position is never summed with, shown inside or listed without a clear separation from the user's real balances (your stablecoin, our collateral figures, any real money). The demo order ticket says it is a demo ticket; the live order-entry notice of your app (orders received and executed by PM MTF Ltd) is NEVER shown on the demo ticket, because no order is received or executed there. The placement rules are docs/12 13.5.

23.11 What differs from live

1. Fills at the mark (23.4): no spread, no depth limit, no partial fill against the book, no market impact and no latency; a taker needs the opposite side of the book to be non-empty and nothing more, and a GTC limit that waits for that side fills at the mark of the moment it is there, where live it would rest on the book and fill at its own price.
2. A resting limit fills whole as soon as the mark reaches it, never waits in a queue and never depends on a counterparty trading through it.
3. Every trigger is evaluated on the mark, whatever source was sent, on marks we poll every 2 seconds: a touch between two polls can be missed.
4. No member-level venue outcome: no member margin refusal, no member liquidation or ADL, no member order or position cap, no venue throttle.
5. The venue's trading states are read every 5 seconds; a shorter halt can be missed, and a state we could not read for 30 seconds reads as trading.
6. A replace is atomic (live it is a cancel and a new order, 4001 and 4002).
7. Funding follows the venue's settlement records shortly after we record them; a later correction of a live settlement's fold line is not applied to the demo.
8. Every demo order needs a fresh mark; live admits a resting limit on a stale one.
9. A demo close-out flattens in the pass that decides it; a live close-out cancels first and flattens at the book's prices on a later tick, so it usually realises more loss.
10. The demo charges our commission scheme only; a fee you charge your users yourself is not simulated.
11. Where the venue publishes no mark, the demo cannot trade, exactly as a live order cannot be checked.
12. THE DEMO RUNS ON ACTIVE MARKETS ONLY: a perpetual market whose offered-instrument row is enabled and that we offer for new exposure (enabled and offered true on GET /market-info, 12.1). An order that would open or add exposure on any other market is refused, as a live one is: a market that is not enabled answers 404 code 4004 "This market is not offered." (to every order without reduceOnly true), a market our operator switched off for new exposure (offered false) 400 code 4000 "This market is not currently offered.". A market switched off for new exposure stays marked, so its demo positions can still be reduced and closed and the demo close-out acts on them as on any other market. We read a market's mark while its offered-instrument row is enabled, while a live client holds a position on it or while a live barrier contract on it is open; a demo position alone never keeps a market's mark read. So if we DISABLE a market (its offered-instrument row) while demo accounts, and no live client, still hold positions on it, those demo positions are no longer marked and no longer closed out until the market is active again: every demo order on that market with reduceOnly true, a close included, is refused with 400 code 4000 "There is no fresh mark price for <symbol> right now. Please try again shortly." (any other order answers the 404 above), and the demo close-out does not act on the account's picture while that market's mark is stale. A reset (23.3), which closes every position without a fill, or the deletion of the account clears them. Live, such a market stays marked until the last live position on it is flat.
13. Nothing in the demo is an order, a position or money of the client.