Integrate with UnifyWire#
UnifyWire supplies read-only trading data to your SaaS backend. Your application authenticates its own users, requests their consent, asks for updates, and reads authorized stored data. It does not need UnifyWire source code or database access.
API origin: https://api.unifywire.com · API prefix: /api/v1 ·
Browser consent origin: https://www.unifywire.com ·
Download OpenAPI 3.1
The foundational closing-facts contract was checked against API implementation revision
8a9e2e65818dc7b88405bae39d5c42057db767ec on October 28, 2026.
Retained-owner consent and withdrawn-empty-recipient recovery were checked against
81c653058af1507b60aae6cab8c3c6a8db07bb1c on November 4, 2026.
The recipient-acquisition amendment is implemented against base
d38d8279f33052b72ebc92dd3e070fd92eb4c3e0 on November 6, 2026.
Its local evidence is separate from deployment and live account acceptance.
All example names, identifiers, prices and amounts below are fictional.
Replace placeholders; never use example credentials or nonce values.
This source revision implements the optional include=closing execution-details
representation (execution-details-v2). This guide describes the implementation;
it does not attest to a server's current deployment or real-account acceptance.
To check support, request the opt-in and require the v2 item and collection
capability before using closing fields. An error or v1 response is not evidence
of a zero balance, and must not trigger a direct-provider fallback.
1. What is available today#
| Capability | Contract and current limit |
|---|---|
| Organization-key authentication and tenant isolation | Implemented. The SaaS backend must also enforce its own user ownership. |
| Fresh cTrader account linking and explicit SaaS consent | Implemented; a signup-free customer return and server-to-server disconnect have been exercised independently. Each integrating SaaS must implement its own authenticated return handler. |
| Explicit asynchronous refresh, saved coverage and restart catch-up | Implemented. Full-gap/restart and stored-data retrieval have accepted evidence for an existing eligible Demo account. A request is not a provider-fetch or freshness guarantee. |
| Additional-account acquisition | Implemented in the recipient-acquisition amendment for supported central cTrader Demo/HEDGED accounts: current owner consent, explicit selection and an accepted refresh admit request-driven acquisition. A retained recipient routes to the same central source stream without a second import/token owner. Consent alone is insufficient. Deployment and later-new-fill live evidence must be verified separately; older workers can still leave a request pending. |
| Trade reconstruction | cTrader HEDGED account type 0 is supported when sufficient retained evidence exists. Unsupported/unverified account types are reported explicitly. |
| Live accounts, other providers and shared-source operation | Do not infer support from a provider descriptor, a Live-format key or a successful connection. The documented central SaaS consent/selection/refresh flow currently requires a Test key and cTrader Demo. The complete multi-SaaS live acquisition journey remains unverified. |
| Retained re-consent | Implemented, with offline coverage; the complete independent retained re-consent browser journey remains unverified. It cannot silently restore a revoked permission. |
The earlier API and website baseline
4c5e1fd1a8ce140882a64b8121a527186f8e6e2a was released and checked with an
independent public-only stored-data client for an existing eligible Demo account. This is
evidence of stored-data delivery, not a
claim that a new customer account, open position, future trade or every financial
field has been verified live. No completion time or continuous-freshness SLA is
promised here.
2. Authentication, ownership and identifiers#
Send every API request from your server, over HTTPS:
Authorization: Bearer uw_test_<KEY_IDENTIFIER>.<KEY_SECRET>
The actual key format contains a 12-character identifier and 43-character secret using URL-safe characters. Keep the complete key in your server secret store. Never put it in browser JavaScript, a consent URL, query parameters, analytics, logs or a mobile application. Obtain an organization Test key through UnifyWire's existing key-management process; there is no public API-key creation endpoint in this contract. Issuing a Live key does not enable Live account synchronization.
The key resolves an organization and environment. It is organization-wide authority, not authentication of a particular trader. Do not accept arbitrary account or connection IDs from a browser and proxy them with this key. For every read, refresh, selection and disconnect, your backend must:
- Authenticate the journal user using your existing session.
- Resolve that user's durable UnifyWire end-user/connection/account mapping.
- Check ownership before making or returning the API request.
- Protect your own state-changing browser endpoints against CSRF and session replay. UnifyWire's server key does not perform your browser authorization.
Organization IDs cannot be overridden in onboarding request bodies. Foreign or
currently unauthorized resources generally return 404; do not infer existence
from a denial. Revoked keys return 401.
| Identifier | Meaning and handling |
|---|---|
Your externalId |
Stable, organization-scoped reference to your own signed-in user, for example journal:user:example-42. It is supplied by you, not a verified broker identity. |
endUserId |
UnifyWire canonical end-user UUID returned by POST /end-users. Save it in your user mapping. |
connectionId |
UnifyWire connection UUID for the consent/access relationship. It is not a provider token or global owner identity. |
Account id / route {accountId} |
UnifyWire canonical trading-account UUID. Use this in /accounts/{id} and selection URLs. |
providerAccountId |
Exact cTrader API account identifier, serialized as a string. It can exceed JavaScript's safe integer range. Do not convert it to a number or use it instead of the canonical UUID in routes. |
brokerAccountNumber |
Broker-facing trading account number, retained as a string or null on account list/detail responses. It may differ from providerAccountId; preserve leading zeros. It is display metadata from the currently authorized account/source relationship, not a globally unique identifier or permission. Missing, conflicting or unavailable labels return null; do not guess from providerAccountId or parse displayName. brokerName is not part of the public account DTO. |
authorizationRevision |
Optional opaque revision on a currently authorized central account. Save it for revision-pinned journal disconnect. It is not a credential. |
| Execution/trade IDs | Treat as opaque strings. Store execution facts by their canonical execution id; upsert reconstructed trades by id and calculationVersion. |
All UUIDs and provider identifiers in examples are fictional. In particular,
40000000-0000-4000-8000-000000000004 below is an example canonical account UUID.
For account labels, use your backend's existing bearer key with
GET /api/v1/accounts (data.items[]) or
GET /api/v1/accounts/{accountId} (data). For example, an authorized account
may contain this subset:
{
"id": "40000000-0000-4000-8000-000000000004",
"provider": "ctrader",
"providerAccountId": "49000001",
"brokerAccountNumber": "5900001"
}
Keep the canonical id for routing and ownership, and label the broker number
separately in your UI. These GETs read retained metadata; they do not fetch from
cTrader or start synchronization. An unavailable label is null, not zero or
the native API ID. Revoked/foreign accounts remain denied. There is no public
reverse lookup by broker number. Connection account selection GETs retain their
existing ID-only response; use the account list/detail for labels.
3. HTTP conventions and errors#
Successful API responses use this envelope:
{
"data": { "example": "endpoint-specific fields" },
"meta": { "apiVersion": "v1", "source": "postgres" }
}
data is an object, array or collection according to the endpoint. A fixture
runtime can identify itself as meta.source: "development_fixture"; that is not
production/provider evidence. API JSON responses use Cache-Control: no-store.
An ordinary authenticated GET may update API-key usage/audit metadata, but it
does not request provider acquisition.
Send Content-Type: application/json for JSON onboarding bodies. Refresh,
selection, deselection and journal-disconnect requests require an empty body:
do not send {}, null, whitespace or a JSON content payload.
Errors have no success data or meta:
{
"error": {
"code": "not_found",
"message": "Selected trading account was not found"
}
}
| HTTP / code | Customer action |
|---|---|
400 invalid_request |
Correct the body, ID, query parameter or header. Do not retry unchanged input. Unknown pagination parameters are rejected. |
401 unauthorized |
Check the server's active key through the established key-management process. Do not repeatedly retry or expose it in diagnostics. |
404 not_found |
Wrong/unauthorized/unselected/ineligible resource, or an unsupported environment for that operation. Reconcile your user mapping and current access. |
409 conflict |
An existing identity/input, target or state conflicts with the operation. Reconcile; do not create a replacement connection automatically. |
412 precondition_failed |
The disconnect revision is missing where required or no longer matches. Fetch current authorized state and require the user's intended action again; do not automatically revoke a newer grant. |
503 service_unavailable |
Maintenance response; defer requests. |
503 backend_not_configured |
Required backend capability is unavailable. Retry later with bounded backoff or contact UnifyWire. |
500 internal_error |
Request outcome may be unknown. Reconcile with GET where available before repeating a mutation. |
The application does not currently define a general API-quota number, a refresh
429 contract or a Retry-After header. Hosting/proxy errors may also occur and
may not use the JSON envelope. Use bounded exponential backoff with jitter for
transient read failures. Keep application retries separate from UnifyWire's
durable provider retry/backoff. Do not blindly repeat an uncertain consent,
connection creation or disconnect.
4. Link an account with explicit consent#
Use the fresh SaaS permission-request flow for an external customer. UnifyWire dashboard Add account is an organization-owner flow; it is not a replacement for your customer session and explicit SaaS consent.
Local dashboard amendment (not yet deployed): Add account creates a fresh
central permission request for the verified owner/admin's workspace user, then
uses the same explicit provider authorization and SaaS approval flow. Existing
legacy connections and permissions are preserved. Returning to /accounts is
only navigation; callback parameters grant no access, select no account and
request no refresh. The signed-in dashboard rereads authorized stored state.
This does not remove the deployed worker's account restrictions or establish
additional-account live acceptance. External SaaS customers keep using the
public endpoints below with their own authenticated users and server-side keys.
Create or recover your end-user mapping#
POST /api/v1/end-users
Authorization: Bearer <PRIVATE_TEST_API_KEY>
Content-Type: application/json
{
"externalId": "journal:user:example-42",
"displayName": "Example trader"
}
Response 201:
{
"data": {
"id": "20000000-0000-4000-8000-000000000002",
"externalId": "journal:user:example-42",
"displayName": "Example trader",
"createdAt": "2026-01-14T09:45:00.000Z",
"updatedAt": "2026-01-14T09:45:00.000Z"
},
"meta": { "apiVersion": "v1", "source": "postgres" }
}
Repeating the same externalId with the same displayName returns the same user
(still 201). A different display name for that existing external ID returns
409. This is a get-or-create identity contract, not an update endpoint. Strings
must be non-empty; these two fields are limited to 255 characters.
Start a fresh permission request#
The UnifyWire browser's read-only review loading uses a 25-second client deadline around an 18-second website processing budget. Each upstream exchange is capped at ten seconds within that server budget. The remaining client time is response headroom, not extra permission validity or a guaranteed latency SLA. Approval has a separate bounded decision path: browser 40 seconds, website 32 seconds, upstream 28 seconds and API processing 24 seconds, with response margins. Original request/review expiry and database lock/statement limits stay authoritative. These are maximum budgets, not a latency guarantee. Decline and OAuth-start retain their existing limits. No decision write is automatically retried.
The original expiresAt remains absolute. If it is reached during loading,
the website offers no approval controls. consent_review_timeout (HTTP 504)
means the loading budget ended; consent_expired (HTTP 409) means the known
review/request expiry was reached. These are browser-website errors, not new
customer API endpoints. On timeout, read the same permission request from
your backend before taking any further action. A server-generated 200 does not
prove the browser received the body/continuity. Never create another request or
repeat an uncertain approval automatically. Repeated loading failure requires
provider readiness repair; an expired request cannot resume or be extended.
If approval acknowledgement is lost, the UnifyWire page checks the already-saved decision once through a separate read-only recovery action. It does not send approval again. The check requires the original request capability and browser binding matched to the original connected, authenticated provider attempt, or the original current browser-owner authority for retained-source consent. It matches the saved selected account, recipient and current active grant/source epoch before returning the immutable SaaS destination/state. Revoked, changed, foreign or expired authority cannot recover a return.
The original HttpOnly continuity cookie is not prematurely cleared or renewed on approval. Reload recovery uses that original cookie and the already-retained server decision; it introduces no browser storage, new source, permission or recovery expiry. An unresolved result shows Check connection result; it is a read, never another approval. After a validated response the page returns automatically, with a fallback link.
consent_decision_unknown (HTTP 504) means acknowledgement did not finish within
its budget; it does not mean approval failed or was rolled back.
consent_decision_unavailable (HTTP 409) means the recovery read cannot qualify
the original saved result. No automatic new request or OAuth follows. These are
browser/server handoff actions, not key-authorized customer API endpoints.
The page's resume can return a validated approved result only when its original
HttpOnly proof/nonce and current saved authority qualify; the request body alone
is insufficient. It generates no new proof, nonce or return state. When the
original browser/review or consumer context has expired, use the SaaS's
authenticated recovery of the durable public decision, preserving the grant and
receipt; never renew old proof, rewrite the original return state or approve
again as recovery. Deployment and genuine owner-to-SaaS delivery proof must be
reported separately from the local contract.
Generate a fresh random return state on your server, for example
randomBytes(32).toString("base64url") in Node.js. Bind it to the initiating
signed-in session, canonical end user, request and expiry in a one-use server-side
receipt. The repeated A value below is a synthetic example only.
POST /api/v1/ctrader/permission-requests
Authorization: Bearer <PRIVATE_TEST_API_KEY>
Content-Type: application/json
{
"endUserId": "20000000-0000-4000-8000-000000000002",
"returnUrl": "https://journal.example/integrations/unifywire/return",
"returnState": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
}
Response 201:
{
"data": {
"requestId": "60000000-0000-4000-8000-000000000006",
"expiresAt": "2026-01-14T09:56:00.000Z",
"consentPath": "/connect/ctrader#request=60000000-0000-4000-8000-000000000006&proof=REDACTED_REQUEST_PROOF"
},
"meta": { "apiVersion": "v1", "source": "postgres" }
}
Both return fields are required together to initiate this signup-free fresh
flow. returnUrl must be canonical absolute HTTPS, at most 2,048 characters,
without credentials, query or fragment. returnState is canonical base64url of
exactly 32 random bytes. Send neither organization IDs nor provider credentials.
The request has a ten-minute expiry; provider continuation/review has a shorter
five-minute lifetime and can expire before the request. Do not extend it locally.
Direct the same initiating browser to
https://www.unifywire.com plus the returned consentPath, preserving its
fragment. Treat the complete URL as sensitive one-use material. Never log the
proof, send it to analytics or strip the fragment before navigation. Keep the
browser through provider authorization, UnifyWire review and the return link.
The normal returned consentPath is the new-account journey: after request
validation, the same browser automatically proceeds to cTrader authorization.
There is no intermediate Continue button, old-account menu, UnifyWire signup or
source-management setup, even if that browser already manages other accounts.
Before navigation, tell the trader that UnifyWire obtains read-only account
information/history and that they will choose the account to share with your SaaS.
After accounts-only Demo authorization, one short confirmation names your SaaS, broker, trading account and environment. A single eligible account is displayed for explicit confirmation; multiple eligible accounts require an explicit choice. The trader clicks Connect to [your SaaS]. There is no separate signup-free checkbox and no automatic sharing of every discovered account. Provider authorization alone is not SaaS approval or acquisition selection.
After a confirmed approval, UnifyWire automatically navigates to the bound return URL, retaining a fallback link. Your server must still verify the original saved request and browser/session state as described below; the return hint is not proof. Timeout, uncertain approval, lost continuation or expiry never starts another request or authorization automatically. Refreshes of an already authorized account use its current grant; they do not require repeating this connection journey.
Existing browser-owned source#
Existing-source reuse is a separate handoff. Append &reuse=1 to the returned
consent fragment to offer accounts already managed by the trader's browser,
without another provider authorization. Do not add this selector to your normal
Connect account / Connect another account action. It grants no authority and fails
closed if no suitable browser-owned account is available; it never falls back to
new OAuth. Unknown, duplicate or combined reuse/source selectors are rejected.
Callers that previously relied on implicit existing-source selection must use
this separate selector or an exact owner_source handoff. Do not use fresh OAuth
to repair missing retained history or silently replace a retained source.
The trader explicitly chooses the account and approves this new recipient; matching a broker account number, organization membership or another SaaS's key is never ownership proof.
The server rechecks the browser credential/generation, exact source/account/authorization epoch and the unchanged recipient review at approval.
Losing that browser authority stops this flow; there is no automatic source adoption or replacement authorization after an uncertain result.
For an exact existing-source-only handoff, use &owner_source=<BROWSER_MANAGED_SOURCE_UUID> instead of reuse=1 after the owner has identified that source.
This selector grants no authority: the browser must still hold the valid credential bound to that exact source.
The review lists only that source's accounts and rechecks the binding at approval. Missing ownership fails closed without provider OAuth or login fallback.
Do not substitute a different source merely because its trading-account number matches: a fresh source does not inherit another source's retained history.
A new recipient receives its own connection/account UUIDs and an independent root grant. Read the original request status, verify the returned account/connection/end user,
then retain its own authorizationRevision. /accounts/{id}/permission-lineage qualifies a later same-source re-consent against a supplied prior revision; it does not return an ancestry certificate for an independent first grant. Another tenant's permission is not a predecessor in this lineage.
A withdrawn, never-acquired enrollment can preserve its own tenant-local account UUID when the owner explicitly consents to a different source for the same verified cTrader principal, application, environment and native account.
This narrow recovery creates a new connection and independent root grant, retaining the old connection and terminal grant. It is unavailable for active grants, other end users, different verified provider identities, acquired records, prior worker targets or previously recovered accounts.
The old grant is not an ancestor of the new root; its old connection stays denied. Account-number equality alone cannot qualify this recovery. Require the newly approved receipt's connection and current account revision rather than reusing the withdrawn connection.
Where this exact source already has committed history, the grant can authorize a retained read projection. Facts stay in place; canonical public execution IDs are stable
in the recipient account's namespace. /executions, /trades, opt-in closing /execution-details, account facts and /sync use the recipient's IDs and current grant checks.
Revoking this recipient denies its reads while preserving retained facts and independent recipients. Reading this history does not request a refresh or select acquisition.
With the recipient-acquisition amendment, explicit selection binds this recipient to the existing central acquisition stream. A bodyless refresh uses its own account ID and current grant, preserves its cutoff across batches/restarts, and exposes appended facts under the same recipient IDs. It does not copy another tenant's credentials or give the customer another tenant's IDs. Older workers require the coordinated amendment before serving this path; retained reads alone do not prove deployment or later-new-fill delivery.
Complete historical equity is not implied by retained trades or today's recorded equity. Unsupported evidence remains unavailable.
The alternative { "endUserId": "..." } request shape is implemented for
existing owner-reviewed sources; it is not the fresh signup-free flow above.
Legacy POST /connections followed by POST /connections/{id}/authorize is also
implemented for organization-owned OAuth connections. Do not substitute it for
fresh central customer consent or use it to adopt a revoked/shared source.
Validate the return on your server#
The browser's return URL carries status=approved or status=cancelled and your
opaque state. It carries no authoritative account IDs or provider token.
- Match and consume your original one-use receipt. Reject changed sessions, end users, replay, expired state or a mismatched request.
- With your private key, GET the saved request ID:
/api/v1/ctrader/permission-requests/{requestId}. - Require authoritative
status: "approved", then GET the returned connection and account using your backend. Require bothendUserIdvalues and their mutual account/connection membership to match your saved user mapping. - Store the canonical account/connection IDs and any
authorizationRevision. Do not automatically select/refresh as an unreviewed side effect of return.
Status example 200:
{
"data": {
"requestId": "60000000-0000-4000-8000-000000000006",
"status": "approved",
"connectionId": "30000000-0000-4000-8000-000000000003",
"tradingAccountId": "40000000-0000-4000-8000-000000000004"
},
"meta": { "apiVersion": "v1", "source": "postgres" }
}
An approved request is a historical consent result; it can remain approved after revocation. It is not proof that access is still current. Pending, expired or cancelled decisions are not grants. If a write/return result is uncertain, read the original request status; do not automatically create a replacement request.
Select separately, then confirm service eligibility#
PUT /api/v1/connections/30000000-0000-4000-8000-000000000003/accounts/40000000-0000-4000-8000-000000000004
Authorization: Bearer <PRIVATE_TEST_API_KEY>
Content-Length: 0
This requests the existing provisioning workflow. A selected account and
syncEnabled response are stored policy, not a running-worker or provider-proof
signal. GET /connections/{id}/accounts returns selected canonical account IDs;
it is not a provider-discovery endpoint. Use authorized /accounts and connection
membership to find linked accounts.
Current acquisition is restricted to an existing approved account scope. A new
SaaS connection can remain pending even after successful consent and selection.
UnifyWire must confirm its acquisition eligibility. Customers cannot enable a
worker, widen its account scope or supply provider credentials through this API.
Initial data has its own proven coverageFrom; do not assume all account history
or a particular initial lookback was acquired.
5. Request a refresh and wait for committed coverage#
For complete financial evidence, select the source-implemented opt-in
described in section 12: POST .../refresh?include=financial, then follow its
returned status URL. Require account-refresh-v2 in the response before relying
on financial completion. The default contract below remains execution-only.
Publication of documentation alone is not deployed or real-account proof.
Account registration and execution-origin proof#
The source-implemented GET-only opt-in reads retained evidence for the same receipt; it does not request a refresh or financial acquisition:
GET /api/v1/accounts/40000000-0000-4000-8000-000000000004/refresh?include=history-origin
Authorization: Bearer <PRIVATE_TEST_API_KEY>
The response preserves account-refresh-v1, refresh, stored and their exact
clocks, adding data.historyOrigin (schemaVersion:"account-history-origin-v1").
Default GET, financial GET and existing POST behavior are unchanged. POST does
not accept include=history-origin; repeated/combined selectors are rejected.
Require historyOrigin.status:"qualified" before using its account-wide
basis:"broker_account_registration" / effectiveAt to qualify absence of
executions before account creation. receipt repeats the exact accepted
requestedAt, requestedThrough and completion status. executionCoverage
reports from, through, completeFromOriginThroughCutoff:true; the range
must agree with ordinary public status and cover the fixed cutoff from origin.
UnifyWire createdAt, the first fill, an empty trade page or a range alone is
not registration proof.
provenance identifies basis:"retained_coherent_provider_capture", its real
physicalObservedAt, an authorized same-account observationUrl,
observationRevision and opaque sourceRevision. Fetch that observation with
your own key; its identity/time must agree. observationRevision is SHA256 of
the canonical JSON response data, without meta: recursively sort object
keys lexicographically, retain array order and encode UTF-8. The server's
sourceRevision binds the exact capture/content revision, current recipient
authorization, registration, original receipt and committed range. It is not
a broker digital signature or a relationship inferred from equal timestamps.
authorizationRevision identifies the same current grant; revoked/foreign
account access remains denied rather than being reported as unavailable data.
Missing capture/registration returns status:"unavailable"; conflicting or
invalid registration, unqualified capture/lineage, incomplete receipt or
origin-to-cutoff coverage returns status:"unqualified". Inspect reason:
registration_missing, capture_unavailable, registration_conflict,
registration_invalid, source_lineage_unqualified, capture_unqualified,
receipt_incomplete or coverage_unqualified. In these cases basis,
effectiveAt, provenance and completeFromOriginThroughCutoff are null.
The ordinary receipt is not rewritten. Do not substitute a date or zero value.
financialEvidence is always "not_asserted". Registration is not a physical
balance/equity at that earlier time, full historical equity, a financial
publication or a guarantee against broker retention limits. A registration
witness can remain qualified when the observation's monetary scale is
unavailable; it does not turn unavailable amounts into zero. Preserve the SaaS's
selected calculation boundary and handle any pre-creation financial state
explicitly. No new consent, provider call or second refresh is needed to read
already-retained proof. Deployment and actual-account proof must be reported
separately from this source-derived contract.
POST /api/v1/accounts/40000000-0000-4000-8000-000000000004/refresh
Authorization: Bearer <PRIVATE_TEST_API_KEY>
Content-Length: 0
The body is empty. There is no date-range, force-refresh, callback, job ID or
Idempotency-Key input. Response 202 is asynchronous; it does not wait for the
provider. It returns the authorized stored data plus refresh status, including
when no new job was created because demand was shared or cooldown applied.
Complete synthetic pending response:
{
"data": {
"schemaVersion": "account-refresh-v1",
"tradingAccountId": "40000000-0000-4000-8000-000000000004",
"refresh": {
"status": "pending",
"requestedAt": "2026-01-14T10:10:05.000Z",
"requestedThrough": "2026-01-14T10:10:00.000Z",
"nextEligibleAt": "2026-01-14T10:15:05.000Z",
"retryAt": null
},
"stored": {
"available": true,
"state": {
"balance": "10000", "equity": "10000",
"marginUsed": null, "freeMargin": null, "currency": "USD",
"observedAt": "2026-01-14T10:00:00.000Z",
"providerObservedAt": "2026-01-14T10:00:00.000Z"
},
"sync": {
"tradingAccountId": "40000000-0000-4000-8000-000000000004",
"provider": "ctrader", "state": "current",
"coverageFrom": "2026-01-14T09:00:00.000Z",
"coverageThrough": "2026-01-14T10:00:00.000Z",
"coverageUpdatedAt": "2026-01-14T10:00:01.000Z",
"latestObservation": {
"observedAt": "2026-01-14T10:00:00.000Z",
"providerObservedAt": "2026-01-14T10:00:00.000Z",
"sourceVersion": null, "openPositionCount": 0
},
"latestRun": null
},
"freshness": {
"schemaVersion": "account-freshness-v1",
"tradingAccountId": "40000000-0000-4000-8000-000000000004",
"provider": "ctrader", "assessedAt": "2026-01-14T10:10:05.000Z",
"assessmentClock": "application",
"executionCoverage": {
"basis": "contiguous_execution_coverage_through",
"coverageFrom": "2026-01-14T09:00:00.000Z",
"coverageThrough": "2026-01-14T10:00:00.000Z",
"coverageUpdatedAt": "2026-01-14T10:00:01.000Z",
"status": "known", "ageMs": 605000, "reason": null
},
"coherentObservation": {
"basis": "retained_coherent_snapshot_observed_at",
"observedAt": "2026-01-14T10:00:00.000Z",
"status": "known", "ageMs": 605000, "reason": null
}
}
},
"statusUrl": "/api/v1/accounts/40000000-0000-4000-8000-000000000004/refresh"
},
"meta": { "apiVersion": "v1", "source": "postgres" }
}
stored.available means an account-state snapshot exists, not that it is fresh
or that complete trading history exists. With no snapshot it is false and
stored.state is null; inspect the separately returned coverage and status.
Cooldown, shared jobs and idempotency#
- The default cooldown is 300 seconds per underlying provider account, shared across endpoints and SaaS customers. It is not a read limit, an automatic five-minute poller or the maximum recoverable gap.
- Concurrent authorized requests share one pending upstream job. Your response remains tenant-local; it exposes no other customer's grant, account, receipt or shared job identity. Sharing work does not make another recipient eligible for acquisition or grant access to its data.
- During cooldown, POST can return
refresh.status: "cooldown", still with HTTP202. It creates no new job; continue reading authorized stored data.nextEligibleAtis admission timing, not a completion ETA or provider SLA. Another customer can cause shared cooldown even if you have no older receipt. - This is demand coalescing, not arbitrary request-key idempotency. After work is
terminal and cooldown expires, another POST can create new demand. There is no
public
Idempotency-Keyreplay contract. - UnifyWire can configure its cooldown independently; a five-second minimum abuse spacing, provider limits, execution bounds and failure backoff still apply. Customers cannot change those settings through the refresh body.
- Accepted jobs may recover long gaps through bounded internal batches and safe restarts without another customer POST per batch. Missing coverage is not reset or skipped. Provider retention, incomplete evidence or failures can prevent completion; there is no promise of unlimited recoverable history.
- An accepted backend refresh is independent of the customer's browser session. Signing out or closing/expiring that session does not itself withdraw the SaaS permission or change the accepted cutoff. The SaaS backend can keep reading status using its existing API key. Explicit disconnect/revocation, changed authority, invalid provider access or an acquisition failure can stop work; browser expiry never permits bypassing those checks. Normal provider-token renewal is separate from renewed customer consent.
- Without demand there is no recurring trading-data polling. A SaaS that wants ongoing updates can schedule explicit refresh requests from its own server.
Status, correlation and completion#
GET the returned statusUrl on the API origin. This is the same resource:
GET /api/v1/accounts/40000000-0000-4000-8000-000000000004/refresh
Authorization: Bearer <PRIVATE_TEST_API_KEY>
It returns 200 with the same response schema. There is no public /jobs
endpoint, job ID, per-refresh receipt-ID URL, webhook completion callback or
refresh-cancellation endpoint. Ordinary status/data GETs do not queue or retry
provider work. Poll with a bounded client deadline and moderate backoff; for
example start at five seconds and increase to 30 seconds with jitter. These are
customer retry suggestions, not server poll timers.
Save {accountId, requestedAt, requestedThrough} from the accepted response.
The GET exposes your latest receipt, not a browsable history of individual jobs.
Do not issue overlapping refresh cycles from your own application. If a later
request replaces that tuple, do not call it the original job: reconcile the
original cutoff against authorized committed coverage and manage the newer
receipt separately.
refresh.status |
Interpretation |
|---|---|
idle |
No retained receipt is returned for you. It does not establish freshness. |
pending |
Demand is saved; work may be waiting for an eligible worker. |
running |
Current account acquisition authority was observed. This is not a socket-health SLA. |
retry_wait |
Durable failure backoff applies; retryAt is supplied. Wait and read status; do not bypass it with repeated POSTs. |
completed |
Your current grant's committed execution coverage reaches at least this receipt's requestedThrough. |
failed |
Terminal job failure budget/state; do not treat partial progress as complete or loop POSTs automatically. Preserve last good data and reconcile. |
cancelled |
Work/receipt is cancelled or its authority is no longer current. Access may instead return 404. |
cooldown |
POST-only admission result; no new refresh was accepted. GET may show the older receipt's actual status. |
For newly created shared work, the cutoff is approximately database time minus
five seconds, rounded to milliseconds. A request joining pending work inherits
that job's existing timestamps and older cutoff. Always use the returned
requestedThrough, not your POST's wall-clock time. Completion can cover beyond
it. Completion does not
require a fresh account observation and does not mean current wall-clock data.
Always assess stored.freshness.executionCoverage and
stored.freshness.coherentObservation independently. Null/unknown ages and
clock-ahead evidence are not zero-age data.
GET /accounts/{id}/sync exposes committed coverageFrom, coverageThrough,
coverageUpdatedAt, latest observation and latest run. A succeeded internal
batch is not completion of the entire refresh. sync.state: "current" means
retained success/coverage, not recent data. A later failed run does not erase
already committed history. GET /accounts/{id}/operations adds recorded policy,
activity, lastSucceededRunAt and freshness; policy enabled, idle, nextDueAt
or a cadence value does not prove a running worker or promise automatic polling.
6. Retrieve executions and reconstructed trades#
Use /accounts/{id}/executions for fill-level facts and
/accounts/{id}/trades for derived position lifecycles. Do not interpret the two
partial closing fills of one position as two independently opened trades.
Executions: immutable fill facts#
Example GET /accounts/{id}/executions?limit=50, response 200:
{
"data": {
"items": [
{
"id": "50000000-0000-4000-8000-000000000001",
"organizationId": "10000000-0000-4000-8000-000000000001",
"endUserId": "20000000-0000-4000-8000-000000000002",
"connectionId": "30000000-0000-4000-8000-000000000003",
"tradingAccountId": "40000000-0000-4000-8000-000000000004",
"provider": "ctrader", "providerExecutionId": "70001",
"providerOrderId": "60001", "providerPositionId": "80003",
"symbol": "EURUSD", "side": "buy", "quantity": "2000",
"price": "1.1", "grossPnl": null, "commission": "-0.1",
"swap": "0", "fees": "0",
"executedAt": "2026-01-14T10:00:00.000Z",
"providerObservedAt": "2026-01-14T10:10:01.000Z"
}
],
"page": { "limit": 50, "hasMore": false, "nextCursor": null }
},
"meta": { "apiVersion": "v1", "source": "postgres" }
}
This example illustrates one fill, not an entire three-fill account download.
grossPnl: null on an opening fill is expected; it is not a realized zero.
side is that fill's side, so sells may close a long position.
Quantities, money, timestamps and provenance#
- Financial values and quantities are decimal strings. Use Decimal/fixed-point arithmetic. Preserve nulls and exact IDs; do not round through binary floats.
- cTrader execution/position quantities are account units, normalized from
provider volume divided by 100. They are not lots. Use
/instrumentsmetadataunitsPerLotonly when available/applicable; never assume every symbol has 100,000 units per lot. Present-day metadata does not prove historical lot size. - Money is scaled from provider integers using its recorded
moneyDigits. Commission, swap and fees are signed adjustments: negative charges reduce P&L; positive rebates/credits increase it. Do not take absolute values or negate them again. - Here,
feescovers the retained P&L conversion fee, not a guarantee that all possible broker fees are represented. - The execution DTO's non-null
"0"commission/swap/fees may come from a default or a not-applicable case. Zero does not by itself prove the provider reported no cost./execution-detailsexposesreported,defaulted_zero,not_applicableand unavailable provenance, currency basis and timestamp origins. Consult it when cost completeness matters. Do not add the close-detail allocation of opening commission to executed-fill commission a second time. executedAtis the provider execution time in UTC. Do not assume every field namedproviderObservedAtis a broker event time: execution details identify application acquisition timing; account-stateobservedAtis a coherent local capture, and itsproviderObservedAtcurrently uses the local P&L response time. Position timestamps can use a provider update time or an observation fallback. Timestamps are ISO 8601 unless a field explicitly says otherwise; retained financial-evidence points usetimestampMs, an integer string of UTC epoch milliseconds. Retain full precision.- Missing provenance, currency, scale or evidence is unavailable, not an invented value. Do not assign a historical currency from today's account currency when the cost or cash record says its currency basis is unavailable.
Opt-in balance after an individual closing fill#
The implementation provides an opt-in representation on the existing endpoint; it does not change ordinary execution-detail responses:
GET /api/v1/accounts/40000000-0000-4000-8000-000000000004/execution-details?include=closing&limit=5
Authorization: Bearer uw_test_<KEY_IDENTIFIER>.<KEY_SECRET>
Omitting include retains execution-details-v1 and its existing fields.
Exactly one include=closing selects execution-details-v2 in both the item
and collection capability. Empty, repeated or different include values are
invalid. The existing ordering and five-row maximum stay unchanged. Keep
include=closing on every continuation request; a cursor from v1 cannot be
used with v2, or vice versa. Ordinary reads acquire no provider data.
Fictional 200 opt-in response; this is a contract example, not a live
response or proof of complete account history:
{
"data": {
"items": [{
"schemaVersion": "execution-details-v2",
"executionId": "50000000-0000-4000-8000-000000000003",
"tradingAccountId": "40000000-0000-4000-8000-000000000004",
"quantityUnit": "account_units",
"executedAt": "2026-01-14T10:10:00.000Z",
"providerObservedAt": "2026-01-14T10:10:01.000Z",
"fillRole": "closing",
"costs": {
"grossPnl": { "value": "2", "basis": "realized_close", "source": "reported" },
"commission": { "value": "-0.05", "basis": "executed_fill", "source": "reported" },
"swap": { "value": "0", "basis": "realized_close", "source": "reported" },
"fees": { "value": "-0.02", "basis": "pnl_conversion_fee", "source": "reported" }
},
"amountCurrency": {
"value": "USD", "observedAt": "2026-01-14T10:10:01.000Z",
"basis": "observed_account_deposit_currency", "applicability": "observed_only",
"availability": { "available": true, "reason": null }
},
"timestampOrigins": {
"executedAt": "provider_execution", "providerObservedAt": "application_acquisition",
"acquisitionBasis": "history_response_acquisition",
"availability": { "available": true, "reason": null }
},
"availability": { "available": true, "reason": null },
"closing": {
"balance": "1002.78", "allocatedCommission": "-0.1",
"moneyDigits": 2, "balanceVersion": null,
"provenance": {
"balance": "provider_reported", "allocatedCommission": "provider_reported",
"moneyDigits": "provider_reported", "balanceVersion": "unavailable"
},
"availability": { "available": true, "reason": null }
}
}],
"capability": {
"available": true, "reason": null, "schemaVersion": "execution-details-v2",
"basis": "first_retained_execution_evidence"
},
"page": { "limit": 5, "hasMore": false, "nextCursor": null }
},
"meta": { "apiVersion": "v1", "source": "postgres" }
}
Join executionId to a canonical fill. closing.balance is the provider-reported
balance after that individual partial or final close, not today's balance,
an EOD balance/equity observation, a lifecycle P&L or a complete deposit/withdrawal
ledger. A closing fill is not necessarily the final fill of its position.
Choose the actual last closing execution of a complete lifecycle when that is
the fact your existing calculation requires.
closing.allocatedCommission is the signed close-detail allocation, which may
include opening commission. costs.commission.value remains the signed
executed-fill commission. Do not add the allocation to execution/trade costs
again, and do not reconstruct the reported balance by summing these two fields.
moneyDigits is the proven scale used to normalize the close money (0 through
18), with provider_reported or retained_account_fallback provenance. Missing
optional balanceVersion is null with unavailable provenance and does not
invalidate otherwise verified close amounts. It is not a coverage/snapshot token.
For an opening/increase, the closing values are null, provenance is
not_applicable, and closing availability says not_a_closing_fill. Missing or
unverified evidence and unavailable scale produce nulls with an explicit
execution_evidence_missing, execution_evidence_unverified or
monetary_scale_unavailable reason. Malformed/conflicting filled raw evidence
fails closed. Check closing availability separately from base fill/cost
availability. Currency retains the existing amountCurrency observed-only basis;
no new historical currency guarantee or missing value is invented.
This representation supplies close facts only. It does not create missing replay intervals, EOD observations, financial adjustment coverage or broader worker eligibility; those remain independent requirements.
Reconstructed position lifecycles#
For this fictional account, suppose the opening above is followed by two closes:
| Fill | Side / units | Price | Realized gross | Fill commission | Swap | Fees |
|---|---|---|---|---|---|---|
| Open | buy / 2000 | 1.1 | null | -0.1 | 0 | 0 |
| Partial close | sell / 1000 | 1.101 | 1 | -0.05 | 0 | 0 |
| Final close | sell / 1000 | 1.102 | 2 | -0.05 | 0 | -0.02 |
With a proven opening boundary and contiguous coverage, /trades returns one
closed lifecycle. Full synthetic response:
{
"data": {
"items": [
{
"id": "57d85db2-9b88-8745-b2e6-1e9073fcd0c7",
"organizationId": "10000000-0000-4000-8000-000000000001",
"tradingAccountId": "40000000-0000-4000-8000-000000000004",
"provider": "ctrader", "calculationVersion": "ctrader-hedged-lifecycle-v1",
"lifecycleKey": "ctrader:position:80003", "providerPositionId": "80003",
"openingAbsenceObservedAt": "2026-01-14T09:59:59.000Z",
"derivationStatus": "complete", "lifecycleStatus": "closed",
"incompleteReasons": [], "unsupportedReasons": [],
"symbol": "EURUSD", "side": "buy",
"openedQuantity": "2000", "closedQuantity": "2000", "remainingQuantity": "0",
"averageEntryPrice": "1.1", "averageExitPrice": "1.1015",
"realizedGrossPnl": "3", "commission": "-0.2", "swap": "0",
"fees": "-0.02", "netPnl": "2.78", "netPnlStatus": "complete",
"openedAt": "2026-01-14T10:00:00.000Z",
"closedAt": "2026-01-14T10:10:00.000Z",
"firstExecutionAt": "2026-01-14T10:00:00.000Z",
"lastExecutionAt": "2026-01-14T10:10:00.000Z",
"sourceExecutionIds": [
"50000000-0000-4000-8000-000000000001",
"50000000-0000-4000-8000-000000000002",
"50000000-0000-4000-8000-000000000003"
],
"derivedAt": "2026-01-14T10:10:01.000Z"
}
],
"page": { "limit": 50, "hasMore": false, "nextCursor": null },
"capability": {
"available": true, "calculationVersion": "ctrader-hedged-lifecycle-v1",
"status": "complete", "coverageFrom": "2026-01-14T09:59:59.000Z",
"coverageThrough": "2026-01-14T10:10:01.000Z",
"inputExecutionCount": 3, "tradeCount": 1, "completeTradeCount": 1,
"incompleteTradeCount": 0, "unsupportedTradeCount": 0
}
},
"meta": { "apiVersion": "v1", "source": "postgres" }
}
Net P&L is realized gross plus the signed commission, swap and fees:
3 + (-0.2) + 0 + (-0.02) = 2.78. The exit price is quantity-weighted.
While a lifecycle remains open or partly closed, final netPnl can be null
with netPnlStatus: "pending_full_close". A complete derivation can describe an
open lifecycle; inspect both derivationStatus and lifecycleStatus.
Collection capability and per-trade reasons must be checked. Missing opening
absence evidence, incomplete/gapped history, unverified/unsupported account type
or unsupported execution patterns cannot be repaired by assuming a flat endpoint
or by inventing executions. Whole reconstruction input is capped at 5,000
executions, separately from page size and recoverable provider history. Above
that cap the route returns an explicit unavailable capability; raising limit
does not bypass it. An empty items list without checking capability is unsafe.
Executions are immutable facts: repeated identical evidence is deduplicated and
conflicting content fails closed. There is no public execution-edit endpoint or
correction/change feed. Reconstructed trades are recalculated from retained
evidence; the same stable trade ID can acquire later closes, costs or a different
completeness state. Upsert it rather than appending a second trade, and retain
its calculation version and source execution IDs. derivedAt is based on retained
source execution creation times, not the GET time. It can change as input changes,
but is not a snapshot/revision token: changes to coverage or opening-boundary
evidence need not advance it. Weighted average prices use 50 significant digits
with half-even rounding; retain source fill prices for original precision.
7. Balances, positions, orders and unavailable financial values#
GET /accounts/{id} returns latestState, which can be null. Its balance/equity
are the latest stored observation, not a balance at each historical execution or
at the final close of every trade. The cTrader account-state projection currently
leaves margin-used/free-margin values null. /observations and
/observations/{observationId} provide retained coherent snapshots and their
observation/acquisition provenance.
/positions returns retained position rows, including closed rows; it is not
guaranteed to be an open-only list. A position disappearing from a complete
snapshot can be marked closed with zero remaining quantity while closedAt and
gross P&L remain null. Do not treat that observation time as the actual execution
close time. Prefer reconstructed lifecycles for trade closing facts.
| Requirement | What you can actually rely on |
|---|---|
Per-fill or per-trade balanceAfter / finalCloseBalance |
Absent from executions, default v1 execution details and reconstructed trades. Opt-in include=closing instead provides conditional closing.balance for an individual closing fill; it is not a general account/EOD balance endpoint. Require the v2 capability before using it. |
| Conditional replay balance at full close | /financial-evidence?from=...&through=... can expose an after_lifecycle / full_close replay point with balance and lifecycleExecutionId only for an exact retained, complete interval. It is conditional reconstructed evidence, not an always-present broker field. Join the lifecycle execution to your fill; never invent a point if capability/evidence is missing. |
| Reconstructing final-close balance yourself | Do not add every fill commission to starting balance. Retained replay allocation can include accrued opening/closing commission differently from an individual closing fill's commission. Use the supplied evidence balanceDelta/balance and provenance when available. |
| Orders | /orders contains retained order observations/revisions, not a trading endpoint or proof of a complete historical pending-order timeline. |
| Deposits and withdrawals | /cash-movements contains retained balance movements, amount/balance/equity only when scale is supported. Its current currency is always null with currencyBasis: "unavailable"; do not infer historical currency. Cash balanceAfter is not a trade final-close balance. |
| Order/cash coverage | /history-requests lists bounded collection receipts. Their complete request response is explicitly not execution or full financial coverage; boundary/filter semantics differ. There is no customer POST to that route to fetch arbitrary history. |
| Symbol / lot metadata | /instruments and /execution-instruments expose retained normalized metadata/provenance. Missing or archived/unmatched information is unavailable, not a license to assume units or current-to-historical applicability. |
Financial evidence, its interval discovery and chain endpoints are reads over retained data. They do not initiate a provider fetch. Their exact ranges, precision, point/payload and chain limits are described in the OpenAPI contract; do not substitute those read limits for total recoverable history.
8. Pagination and consistent reconciliation#
Collection responses use data.items and data.page:
{ "items": [], "page": { "limit": 50, "hasMore": false, "nextCursor": null } }
This is a collection fragment; the HTTP response still has the outer data and
meta envelope. Follow nextCursor unchanged until hasMore is false.
URL-encode it; treat it as opaque and bound to the same resource/account.
Only limit and cursor are accepted on standard paged routes; there is no
generic from, updatedSince, endUserId, sort or date-filter parameter.
Financial-evidence routes have their own explicit query contract instead.
| Collection | Default / maximum limit |
Order |
|---|---|---|
| Connections, accounts, positions, executions, instruments, execution-instruments, trades | 50 / 100 | Ascending resource time, then ID; execution order is executedAt, then ID. |
| Observations | 1 / 5 | Newest first. |
| Execution details | 5 / 5 | Ascending execution time, then ID. |
| Orders, cash movements, history requests | 5 / 5 | Newest observations/receipts first. |
Repeated/unknown pagination parameters or an out-of-scope cursor return 400.
GET /providers, a selection response, status response and permission lineage
are not standard paged collections.
Pagination is keyset traversal, not a cross-page snapshot, signed snapshot token, delivery acknowledgment or append-only change cursor. Different GETs can observe later committed data; each read rechecks authorization. New backfilled rows before an old cursor can be missed if it is used as a permanent watermark.
After a completed refresh, reconcile the account from a fresh first page, deduplicate execution IDs and upsert trade IDs. Read coverage/observation and any authorization revision before and after the traversal; if those changed, restart the affected reconciliation. Do not merge partial pages from different accounts, recipients, resource types or revoked permissions. The API currently has no public immutable multi-resource snapshot ID or change feed.
9. Disconnect only your journal's access#
Your trader disconnects inside your authenticated journal. They do not need a UnifyWire owner cookie, UnifyWire login or 30-day renewal for this action.
Use the end-user-scoped route from your backend, with an empty body. Pin the
intended consent generation using the current account's authorizationRevision
saved in your server-owned mapping before revocation:
DELETE /api/v1/end-users/20000000-0000-4000-8000-000000000002/connections/30000000-0000-4000-8000-000000000003
Authorization: Bearer <PRIVATE_TEST_API_KEY>
If-Match: "unifywire-customer-authorization-v1:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
Content-Length: 0
Response 200:
{
"data": {
"connectionId": "30000000-0000-4000-8000-000000000003",
"status": "disconnect_requested",
"cleanupState": "requested",
"workerCleanupConfirmed": false
},
"meta": { "apiVersion": "v1", "source": "postgres" }
}
The quoted revision is an opaque value from the API, not a hash you compute.
Malformed If-Match is 400; a different/newer grant or missing revision where
lineage requires one is 412 without revoking that newer permission. Headerless
single-generation compatibility is implemented, but do not build a new journal
integration around it: successor consent makes the revision necessary.
This operation checks your organization, exact end-user mapping, connection and
central account permission. Wrong tenant/user or unsupported legacy access is
not granted through this route. Repeating the same revision is idempotent;
it does not create another withdrawal audit. An unknown result must be reconciled
before another write. The organization-wide DELETE /connections/{id} is a
separate legacy-compatible operation without the end-user assertion/If-Match
handling; it is not the recommended journal-user disconnect route.
Revocation blocks later authorized reads and prevents revoked queued deliveries or later publication under that grant. In-flight work is checked/fenced and cancellation is requested. A read admitted before revocation may finish; a response already in transit cannot be recalled. A disconnect response does not confirm every socket/process has stopped. Shared provider sources, encrypted credentials and retained history are not deleted as a side effect of withdrawing one central SaaS permission. Another SaaS's independent authorized access remains. With no authorized selected consumers, that account loses acquisition eligibility; pending/running work is cancelled or settled safely. Internal delivery records do not imply a public webhook/subscription API exists.
DELETE /connections/{id}/accounts/{accountId} is deselection, not withdrawal
of the SaaS permission. It requests cancellation of that account's acquisition.
Do not label it “disconnect journal” or assume it denies all authorized history
reads. Global owner source disconnect and provider-side cTrader revocation are
also separate protected operations.
Reconnect and retained identity#
Revoked permission never silently becomes active because the broker/profile
number matches, a token refresh succeeds or the browser logs in again.
Re-consent must be a fresh explicit SaaS decision. The retained-consent request
shape is implemented on POST /ctrader/permission-requests:
{
"endUserId": "20000000-0000-4000-8000-000000000002",
"reconsent": {
"connectionId": "30000000-0000-4000-8000-000000000003",
"tradingAccountId": "40000000-0000-4000-8000-000000000004",
"previousAuthorizationRevision": "unifywire-customer-authorization-v1:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
},
"returnUrl": "https://journal.example/integrations/unifywire/return",
"returnState": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
}
Use a fresh random state, not the example or an earlier receipt. Where the
retained connection, original owner/source, settled withdrawal and browser
authority are eligible, approval creates a new authorization revision while
preserving the canonical connection/account and the revoked predecessor.
/accounts/{id}/permission-lineage exposes the authorized current lineage.
Eligibility is rechecked; an existing UUID is not proof it can be re-consented.
The complete independent retained browser journey is still unverified.
Journal withdrawal does not require prior account deselection. The revision-pinned,
bodyless DELETE /api/v1/end-users/{endUserId}/connections/{connectionId} withdraws
that grant and its logical sync selection itself. A completed central acquisition
stream may remain available for other authorized recipients. Its availability does
not authorize a revoked journal to read, request a refresh or publish results.
Retained re-consent waits for that journal's prior work/leases to settle and its
selection to be withdrawn; it does not require stopping the shared worker or stream.
If prior work has not settled, the browser review returns HTTP 409 with public error
code consent_not_ready, approves nothing and does not start another connection.
Check the existing request's status from your backend. After cleanup is confirmed,
the owner can reopen the original returned consent URL in the same owner browser
while that request remains valid. There is no automatic retry, extended expiry or
public readiness certificate. An expired request is terminal: reconcile it before
creating a fresh retained-consent request with a fresh return state. Do not reset
the source or reimport history. Fresh approval retains the same connection/account
IDs and requires a separate explicit sync selection and refresh for new acquisition.
The separate browser-owner management credential lasts 30 days and requires
explicit renewal while valid. That is for global owner management, not journal
disconnect. Losing/expiring it cannot recover a source merely by matching
account or profile IDs. Provider reauthorization/source repair is distinct from
grant re-consent; there is no generic public /reconnect endpoint or guaranteed
automatic history transfer/owner adoption. Do not fall back to a fresh connection
after an uncertain retained request.
Owner recovery when the original browser credential is unavailable#
UnifyWire supports operator-assisted recovery of one exact retained source. This is separate from SaaS consent and provider reconnect. Contact UnifyWire support to verify the original owner and identify the retained source. An account number, a matching cTrader profile, tenant membership or a customer API key is not enough to authorize recovery. If ownership cannot be independently verified, recovery is refused; creating another OAuth source does not adopt the old one.
After verification, the operator provides a private, single-use link to
https://www.unifywire.com/connect/ctrader/owner/recover. It expires ten minutes
after issuance. Keep it private. In the intended browser, check the exact source
reference and native account IDs, then explicitly confirm replacement browser
management. The replacement is a new Secure, HttpOnly browser credential, valid
for thirty days. The former credential loses management of this source only;
any other sources it manages are unchanged.
Recovery preserves the original source/principal, provider authorization, SaaS permissions, recipient account/connection IDs, retained data and trade IDs. It does not fetch data, import history, select accounts or start synchronization. It cannot reopen an expired consent request or reactivate a revoked grant. Following recovery, use a new ordinary retained-consent request where needed; the owner still approves its exact SaaS recipient manually. The existing normal source reconnect remains available for its supported suspended-credential state, with the original full recipient review and cTrader OAuth confirmation.
If the recovery confirmation response is lost, use Check saved recovery outcome in that same tab/browser. It reconciles the saved result using the provisional browser credential; it does not repeat the write. A consumed link by itself cannot reissue a credential in a different browser. Stop on an expired or changed review and contact support. There is no customer API-key endpoint that issues or approves owner recovery. This source contract does not by itself prove deployment or a successful live recovery; those results must be reported separately.
10. End-to-end backend walkthrough#
- Authenticate and map: obtain a Test key; authenticate the trader in your journal; get-or-create an end user and save its canonical ID.
- Link: generate your one-use session-bound return state; POST the fresh permission request; send that same browser to the exact returned consent URL.
- Validate return: recheck your session/state/expiry, GET the saved request,
then GET its current account and connection. Save their user mapping and
authorizationRevision; never trust browser status alone. - Select explicitly: empty PUT the exact account selection. Confirm with UnifyWire that this recipient/account is in the currently served acquisition scope. A linked/selected account alone cannot prove it.
- Refresh: empty POST
/accounts/{id}/refreshonce. Save the exact request timestamps/cutoff; return stored data and a pending label to your user. - Wait: GET the same status URL with a bounded polling policy. Respect cooldown/backoff. Handle failed/cancelled/denied states; do not submit a POST for every catch-up batch or mistake one succeeded batch for completion.
- Retrieve: once the receipt is completed and its cutoff is covered, read freshness independently. Traverse executions/trades from the first page, dedupe/upsert, check reconstruction capability and reconcile concurrent changes. Preserve Decimal strings, signed costs, nulls and provenance.
- Disconnect: authenticate/authorize the user and protect your browser action against CSRF; your backend DELETEs the exact mapped end-user connection with its saved quoted revision. Verify later account/connection reads are denied. Record withdrawal, while showing cleanup as requested rather than confirmed.
The OpenAPI download describes all implemented /api/v1 methods and schemas,
including optional retained-evidence routes. No step requires private SQL, source
access, provider tokens in the journal, or a UnifyWire owner cookie for journal
disconnect. Eligibility and unsupported data remain real limits, not steps your
client should work around.
11. Remaining contract gaps#
- Additional-account/recipient acquisition needs the compatible recipient-acquisition release, current owner consent and explicit selection. Linking alone is insufficient; documentation publication does not establish live acceptance.
- The full retained re-consent and multi-SaaS shared-source live journeys remain unverified. Shared-job isolation tests are not equivalent live proof.
- Public account DTOs omit the broker-facing account number/broker label that consent and dashboard views can display.
- Closing details are implemented in the source revision above; public deployment and real-account acceptance require separate verification. There is still no general execution/trade balance-after field, guaranteed EOD timeline, complete fee taxonomy, cash-movement currency, historical symbol applicability guarantee or universal account-mode/Live support.
- There is no public individual job ID/history/cancel API, webhook subscription, correction/change feed or cross-request snapshot token. Use the actual latest receipt, coverage, current access and reconciliation semantics above.
- No general request-per-minute quota, completion SLA or
Retry-Aftercontract is specified by this application. Keep client work bounded and handle hosting failures without assuming they follow the application JSON envelope.
Joining an observation to a financial boundary#
GET /api/v1/accounts/{id}/observations/{observationId}/financial-boundary
uses the same private server API key and current account authorization as the
observation detail route. It starts no refresh. Supply no query parameters.
The response's observationId, observationRevision and observedAt identify the
unchanged original observation. observationRevision is SHA256 of canonical JSON
for that observation's response data (object keys sorted recursively, array order
preserved). When availability.available is true, boundaryRevision equals the
revision of the same physical capture in financial-evidence.boundaries.
Join both scope and revision, and check observedAt; equal balances alone are
not capture identity. An unavailable capture returns a null boundary revision and
its explicit availability reason. The ordinary observation and financial payloads
remain unchanged, including their previously saved revisions.
This relation exposes neither a private snapshot ID nor a native provider DTO.
It proves no covered interval, native activation request, calculation admission or
current freshness (coverageProof is always false). Validate the relevant complete
financial resource and its actual physical timestamps separately. Never substitute
an import timestamp for evidence coverage or rename a derived calculation cutoff
as a physical observation. Discovery cursors support the actual retained interval
duration at every supported page size, including 5; the cursor is bound to the
organization, account and requested range, not to a ten-minute interval limit.
12. Automatic financial refresh (explicit v2 representation)#
Source implementation amendment CT-FIN-01, based on c5fd3c4. Deployment and
real-account automatic recovery are separate verification requirements; this
section alone does not establish that they passed.
POST /api/v1/accounts/40000000-0000-4000-8000-000000000004/refresh?include=financial
Authorization: Bearer <PRIVATE_TEST_API_KEY>
Content-Length: 0
The same authorization, account restrictions, empty body, shared-account job, 300-second cooldown, retry backoff and admission spacing apply. This does not select an account, widen worker eligibility, grant consent or force a provider read during cooldown. Concurrent pending requests share the fixed cutoff; an explicit v2 POST can add a financial requirement to its own still-pending v1 receipt. GET never upgrades a receipt or creates work. Old terminal receipts remain unchanged.
The response uses account-refresh-v2 and returns a status URL ending in
?include=financial. Follow that exact URL using GET. Existing stored data
remains readable while work is pending. Correlate the account, requestedAt
and fixed requestedThrough; do not replace an accepted request after a
timeout or ask for another POST to finish its batches.
The additional refresh.financial object is:
| Field | Meaning |
|---|---|
requiredFrom |
Genuine starting physical endpoint bound at admission, or null when no financial work was requested. New work extends the latest independently proven published endpoint; with no published endpoint, it starts from the earliest eligible complete capture. |
executionComplete |
Committed canonical history reaches this receipt's fixed cutoff. This alone is insufficient for financial completion. |
status |
not_requested, pending, or completed. Pending means evidence has not committed, including when the outer receipt has failed/cancelled. |
through |
Committed financial endpoint, or null before publication. |
physicalObservedAt |
Actual retained physical endpoint, distinct from the logical cutoff and completion/import times. |
resourceUrl |
Authenticated exact financial-evidence GET path after publication, otherwise null. Read its source revision, capture boundaries and provenance independently. |
For example, after publication the additional object can be:
{
"requiredFrom": "2026-01-14T10:00:00.000Z",
"executionComplete": true,
"status": "completed",
"through": "2026-01-14T10:10:08.125Z",
"physicalObservedAt": "2026-01-14T10:10:08.125Z",
"resourceUrl": "/api/v1/accounts/40000000-0000-4000-8000-000000000004/financial-evidence?from=2026-01-14T10%3A00%3A00.000Z&through=2026-01-14T10%3A10%3A08.125Z"
}
A corresponding logical cutoff could be 10:10:00.000Z; it stays unchanged.
The producer covers that cutoff with evidence between real physical endpoints;
it does not manufacture an observation at the cutoff. A consumer's freshness
rule must still evaluate the correct physical clock and its own calculation
window. A later capture cannot make an old fixed cutoff recent.
The required interval begins at requiredFrom. Extending a recent proven
endpoint does not declare older disconnected intervals complete or repair every
historical gap. Validate the exact older financial chain separately; an
unavailable chain remains unavailable. The admitted start and logical cutoff
stay fixed while internal batches and worker restarts finish the work.
Only v2 refresh.status=completed and
refresh.financial.status=completed assert full required publication. The worker
retains successful bounded cash/quote input pages across turns/restarts,
reconciles unknown commits before repetition, and publishes through the existing
fenced writer. It cannot publish from failed, incomplete, revoked or unfenced
work. The default v1 completed remains execution-only.
Unavailable starting captures, incomplete/malformed history, missing valuation metadata/seeds, unsupported account modes, or inconsistent provenance fail closed. In the previously deployed baseline, nonzero independent cash adjustments are unsupported by this automatic reconstruction path; they are not treated as zero or hidden by a successful execution refresh. There is no guarantee of full historical equity outside published proven coverage. No autonomous provider polling occurs after all accepted demand is satisfied. Stored-data/status GETs do not refresh.
Financial identity links#
GET /api/v1/accounts/{id}/financial-evidence-links?from=<exact UTC millisecond>&through=<exact UTC millisecond>
uses the same authentication, tenant/account authorization and retained financial validation as /financial-evidence.
It does not fetch or reconstruct data. Match its financialSourceRevision to the original financial resource before using any links.
If unavailable, baseline is null and cashMovements is empty; this is not an assertion of no cash activity.
Existing financial resource bytes, revisions and IDs are unchanged.
For a reconstructed start, baseline.sourceRevision equals the financial resource's baselineProof.sourceRevision,
and baseline.boundaryRevision equals its boundaries.start.boundaryRevision.
physicalAnchorBoundaryRevision equals its physical boundaries.end.boundaryRevision and can be joined to
/observations/{observationId}/financial-boundary. Verify the actual anchor timestamp as well as these identities.
The derived start remains observedAt:null; this link does not turn it into a physical capture or supply pre-origin history.
Each financial cash link supplies reference, cashMovementId, balanceVersion and occurredAt.
Read the paginated /cash-movements?include=financial&limit=5 ledger, following its cursors with the same include option.
Its opt-in financialLink.reference and balanceVersion must match the financial link and the replay's
cashMovementAdjustment; cashMovementId must equal the ledger row's id.
Then verify the signed delta, post-event balance and timestamp. Matching amounts/times alone is insufficient.
A missing ledger balance version stays null, never zero. Default ledger responses, IDs, revisions and pagination stay unchanged.
Cash flows are separate from trade P&L; these links do not change the consumer's cash-adjustment rules or justify counting commission twice.
These contract additions do not resolve unavailable historical valuation metadata or a selected start before proven coverage. They cannot make an unavailable replay complete. Proper SaaS consent remains separate from financial qualification.
13. Customer-history contract and availability limits#
This section describes the customer-history implementation. Acquisition eligibility and live verification remain account-specific; the additional-account restrictions above still apply. No complete new-account live acceptance is asserted here.
For supported Test/Demo HEDGED accounts, the existing database target discovery
and provisioning path can consume the first accepted refresh without a seeded
snapshot. Selection still does not fetch data. Financial intent can remain
pending with requiredFrom:null while that same receipt obtains its first real
capture. The immutable requestedAt and requestedThrough do not change.
New customer receipts request all broker-available executions and cash history from the provider's account-registration boundary through the fixed cutoff; there is no customer start-date parameter or 30-hour total lookback. A bounded turn may save only a prefix. Later turns/restarts resume from durable complete range receipts, including older holes despite a recent checkpoint. Empty cash windows are retained as evidence. An uncertain commit is reconciled before repeating its write. Existing receipts keep their original obligations. Your challenge/report start date selects your calculations, not the producer's collection period. Complete broker responses prove only their reported ranges; undocumented broker retention and unavailable data must not be hidden.
Deposit/withdrawal deltas are signed native money with explicit scale, post-event balances and balance versions. They are separate account balance events, not trade P&L. Overlapping pages deduplicate the ledger identity, not equal timestamps or amounts. Close-allocated commission remains distinct from fill commission: never add both. Missing scale/version, unknown operation types, inconsistent balances or ambiguous order cannot become zero or complete equity.
Where origin-to-anchor evidence qualifies a reconstructed historical boundary,
financial resources explicitly use schemaVersion:"financial-evidence-v2" and report:
{
"baselineProof": {
"basis": "reconstructed_history",
"effectiveAt": "2026-01-01T00:00:00.000Z",
"physicalAnchorObservedAt": "2026-04-01T12:00:08.000Z",
"sourceRevision": "<opaque-revision>"
},
"boundaries": {
"start": {
"observedAt": null,
"effectiveAt": "2026-01-01T00:00:00.000Z",
"basis": "reconstructed_history",
"balance": "0",
"equity": "0",
"openPositionCount": 0,
"boundaryRevision": "<opaque-revision>"
}
}
}
This is an abbreviated fictional fragment. The physical end and source revisions
are supplied by the complete resource. No historical physical capture is created
at effectiveAt. Cash points use before_cash/after_cash; an after_cash
point includes cashMovementAdjustment:{reference,delta,balanceVersion}. Its
reference is opaque and tenant scoped. Recorded physical v1 boundaries keep their
existing representation.
For trade lifecycles, a qualified registration boundary can prove an account had
no pre-existing position at creation. It is reported as
openingAbsenceBasis:"account_registration" and
openingAbsenceEffectiveAt, with openingAbsenceObservedAt:null. Complete
execution coverage and the opening/closing fills remain mandatory. This can
establish closed-trade totals without proving historical equity minima.
Traded history additionally requires separately retained metadata observations
that bracket the exposure and agree on the relevant product, swap timing and
conversion paths. The first complete capture must finish before exposure; a
metadata acquisition-start label alone does not establish that its response was
available then. The later metadata acquisition must start after the exposure.
Known intermediate contradictions fail qualification. The optional v2
valuationProof reports basis:"retained_metadata_observations",
exposureFrom, exposureThrough, knownBeforeExposureAt,
laterMetadataAcquisitionStartedAt and an opaque sourceRevision.
These are metadata-provenance bounds, not invented historical account snapshots.
This amendment is local/source-implemented; no new deployment or live account
acceptance is established by this guide.
Historical trading equity remains unavailable when historical product, currency, conversion or swap applicability is unqualified. Comparing today's catalog with itself or matching a final balance is insufficient. The raw trades and cash can be imported correctly while financial evidence remains unavailable. Missing origin is likewise explicit; first trade, customer date and now-minus-30h are never substituted. These limitations do not establish permanent broker loss. Historical bid and ask seeds and all needed quote/conversion pages must be complete. A close-time conversion rate cannot value the whole earlier exposure. Aggregate realized swap does not locate multiple earlier rollover charges. Missing inputs produce incomplete/unsupported results, never zero equity or a realized-trade-profit substitute for account equity. Drawdown/rule calculations must use qualified equity and separate cash adjustments for their actual window.
An affected receipt returns refresh.status:"failed" with an optional
unavailableReason. Explicit financial status is unavailable, has the same
reason, and has no resource URL. Allowed reasons are
history_origin_unavailable, historical_trading_metadata_unavailable,
historical_baseline_unavailable, cash_metadata_unavailable, and
cash_operation_unsupported. This terminal limitation does not authorize an
automatic replacement request or remove the account/grant/history. Other valid
consumers continue. Stored-data and status reads remain passive.
Individual acquisition, transaction, payload, quote and financial-result limits remain bounded. A long or highly active financial replay can still exceed its supported evidence capacity; successful trade/cash import must not be advertised as full historical equity. Production support for Live, netted or spread-betting accounts and arbitrary additional-account activation is unchanged.