Developer documentation API v1
Authorization and execution state
Bind authority to an exact action and preserve uncertainty across the venue boundary.
Order state under uncertain delivery
An action-bound approval
The action constructor converts a research result into an exact proposal by resolving the account, instrument, direction, quantity, quote and costs. The authorization binds the principal and account to that proposal’s revision, digest, policy and expiry. A body field such as approved:true cannot supply this authority.
Dispatch re-evaluates revocation, account state, quote validity and aggregate commitments. A required single-use authorization is consumed atomically with local admission. The venue’s acknowledgment then establishes its own acceptance state; local authorization alone does not imply a fill.
Action request
POST /v1/actions also requires an Idempotency-Key. The authorization is obtained through a separately authenticated approval or delegation flow; this request does not create that authority. Arbitrary calldata and credentials are excluded.
{
"proposal_id": "proposal_example_1",
"proposal_revision": 3,
"authorization_ref": "auth_example_1"
}State transitions
| Current state | Event | Next state or constraint |
|---|---|---|
| accepted | Preflight succeeds | ready; resources reserved if required. |
| accepted / ready | Permission denied or expired | rejected before external submission. |
| ready | Dispatch begins | submitting; durable attempt identity recorded. |
| submitting | Venue acknowledgment | open, partially_filled or filled. |
| submitting | Response lost | submission_unknown; reconcile before any new submission. |
| open / partially_filled | Fill or cancellation acknowledgment | Update unique fills; cancellation applies to remaining quantity. |
| Any externally active state | Status disagreement | Preserve reconciliation discrepancy separately. |
Action projection after an uncertain submission
Zero recorded fill quantity here means no fills have yet been observed in this projection. It does not prove the venue has executed nothing.
{
"action_id": "act_example_1",
"proposal_id": "proposal_example_1",
"execution_state": "submission_unknown",
"reconciliation_state": "pending",
"venue_order_ref": null,
"filled_quantity": {"asset": "instrument_example", "atoms": "0", "scale": 0},
"fills": [],
"next_step": "query_existing_action"
}Concurrency and duplicate effects
Capital checks include other agents and outstanding orders. Conditional reservation updates serialize competing claims on the same balance, preventing two agents from independently spending a shared amount.
External recovery uses venue idempotency, stable client-order identifiers and status lookup according to the connection. Fills are deduplicated within account and venue identity. A timeout after dispatch leaves the outcome unresolved; capital remains committed until reconciliation establishes whether the venue accepted or executed the action.
Cancellation and revocation
Revocation blocks new authorized effects; it cannot undo an already accepted external order. Cancellation is a separate venue request whose result must be observed. Partial fills survive cancellation. Brokerage execution, on-chain swaps and derivatives require separate adapter semantics and cannot share a fictional universal atomic rollback.
A lost acknowledgment, step by step
An action is admitted with a stable identity and capital reservation. The venue accepts its order, but the acknowledgment is lost before Seer records the external order reference. The action becomes submission_unknown and its reservation remains committed.
Recovery queries the venue using the connection’s stable submission identity. If the venue reports an open order, Seer attaches that reference and resumes observation. If it reports fills, those fills are ingested by stable identity. An authoritative rejection or absence is interpreted according to the venue’s recovery guarantees; a transport timeout alone is neither. A second newly identified order would risk duplicating the economic effect.
Remaining order quantity
The fill set is deduplicated by stable venue identity within the account. Cancellation changes the status of the unfilled remainder; it does not subtract already executed quantity. Amendments or replacements retain their own linkage and accepted quantity revision.
Construct an exact execution proposal
POST /v1/execution-proposals. Example prices and expiry are illustrative; use an actual current quote and account snapshot. The 201 response identifies the proposal revision and digest for account-owner approval.
{
"account_id": "account_example_1",
"account_snapshot_id": "acctsnap_example_1",
"instrument_id": "equity:listing:apple-common-xnas",
"side": "buy",
"quantity": {
"asset": "equity:listing:apple-common-xnas",
"atoms": "10",
"scale": 0
},
"order_type": "limit",
"limit_price": "100.25",
"quote_asset": "USD",
"time_in_force": "day",
"expires_at": "2026-10-01T20:06:00Z",
"quote_ref": "quote_example_1"
}Cost references and signed positions
ExecutionProposal.cost_estimate_ref is an artifact ID resolved through GET /v1/artifacts/{artifact_id}; its kind is tool_result and its tool is execution.cost_estimate. The exact proposal’s quote_ref identifies the size-specific quote used by that cost artifact. A quote with inadequate fillable size, unavailable status or expired validity cannot satisfy executable preflight.
Account Position.quantity is an unsigned magnitude paired with side=long or short. Signed exposure is +quantity for long and −quantity for short, followed by the instrument’s contract multiplier and valuation rules. Order quantities remain nonnegative, with buy/sell describing the requested transaction. A sell does not imply permission to create a short position.