Developer documentation API v1
Settlement and reconciliation contracts
Track financial movement independently of job completion and order state.
Settlement record
GET /v1/settlements/{settlement_id} returns the movement and reconciliation record. The asset and scale are explicit; a USD movement is not denominated in SCC.
{
"settlement_id": "set_example_1",
"action_id": "act_example_1",
"movement_ref": "movement_example_1",
"amount": {"asset": "USD", "atoms": "12500", "scale": 2},
"state": "pending",
"confirmation_basis": "account_statement",
"external_ref": "external_example_1",
"observed_at": "2026-10-01T20:06:00Z",
"reconciliation_state": "pending"
}Independent dimensions of state
Execution state tracks the order. Settlement state tracks asset or money delivery. Reconciliation state tracks agreement between compared records. A filled order can remain unsettled; a matched fill does not establish that every cash movement is final.
For an on-chain route, retain chain, transaction reference, block identity and the required confirmation policy. Observed inclusion can be reversed by a reorganization before the relevant finality condition. No fixed block count in this reference is a universal guarantee.
Reconciliation residual
Residuals compare the same account, asset, cutoff, precision and lifecycle basis. Pending settlement explains a difference only when the referenced movement and amount match. Exact-quantity sources reconcile at their recorded precision; valuation tolerances are explicit and separate from quantity reconciliation.
Discrepancy classification
| Class | Investigation |
|---|---|
| Timing difference | Check cutoff, delayed fills and pending settlement. |
| Missing event | Retrieve authoritative transactions and deduplicate before posting. |
| Quantity or fee mismatch | Inspect unit conversion, corporate actions and fee currency. |
| Chain reorganization | Re-evaluate inclusion and dependent movements. |
| Unresolved | Restrict dependent spending and preserve evidence for review. |
Correcting records
Corrections append an attributable adjustment or reversal linked to the original movement. Both observations remain available, and balance projections are reproducible from accepted events and corrections.
Financial institutions and networks establish custody, transfer and finality for their respective routes. Seer’s reconciliation records agreement or discrepancy against those observations, including pending obligations and unresolved external states.
Three-dimensional lifecycle state
An action can be execution=filled, settlement=pending and reconciliation=matched. These statements are compatible: the observed fill agrees with the venue, while final delivery remains outstanding. Conversely, a confirmed transfer can still have a reconciliation discrepancy if the amount or account differs from the expected movement.
The joint state is therefore a product of separate state spaces, not one success flag. Interfaces expose each dimension with the relevant observation cutoff. This supports recovery without interpreting one completed stage as proof that every downstream obligation is satisfied.
Event-derived balance projection
B at t₀ is the baseline quantity in one denomination. The sum contains only postings effective after that baseline and through t, selected at the query’s system-revision cutoff. Δ is a signed accepted posting, including linked reversals. Market valuation is separate; price changes do not alter the quantity ledger.
Find all movements for an action
GET /v1/actions/{action_id}/settlements lists associated movement records. A single trade can produce several asset, cash and fee movements; inspecting only one settlement ID is insufficient to establish completion of the whole action. The collection follows the same cursor and ownership rules as other resources.