---
title: "Reconcile one Hyperliquid order from authoritative venue evidence"
method: POST
path: "/v1/agent/futures/reconcile-order"
---

# Reconcile one Hyperliquid order from authoritative venue evidence

`POST /v1/agent/futures/reconcile-order`

## Request

- Base URL: `https://www.farmdash.one/api`
- URL: `https://www.farmdash.one/api/v1/agent/futures/reconcile-order`
- Auth: one of:
  - HTTP bearer
  - none

Read-only and zero-custody: signs nothing, submits nothing, and never retries
an order. Durable order/fill evidence uses the existing idempotent accounting
path; balances are not execution evidence. agentAddress is the venue API-wallet
signer, not the session agent. accountAddress identifies its delegated owner.
Known bounded reservations are discovered by account, network, market and OID.
Optional controlActionId selects one exact durable action for cancellation or
unknown-submission recovery. Selection is not proof of OID linkage; unproven
submissions remain unknown and liability stays held. For a batch cancellation,
reconcile every signed target OID. A bounded reservation result is policy
bookkeeping, not proof of a fill, final cancellation or recognized revenue.

## Request body

- ReconcileOrderRequest
  - `agentAddress` string, required: Venue API-wallet signer; never replaced by the session agent
  - `accountAddress` string: Delegated equity owner; defaults to agentAddress
  - `coin` string, required: Default Hyperliquid perp market symbol, normalized uppercase
  - `orderId` integer, required
  - `intentHash` string, nullable: Optional submission provenance selector; caller hash alone is not evidence
  - `controlActionId` string, uuid: Optional exact durable bounded control action selector, not authority or proof of OID linkage

## Response `200`

Authoritative venue evidence recorded durably; bounded context is present only when matching reservations exist

- ReconcileOrderResponse
  - `ok` true, required
  - `reconciliation` FuturesOrderReconciliation, required
    - `accountOwner` string, required
    - `signerAddress` string, required
    - `perpDex` string, required
    - `coin` string, required
    - `orderId` integer, required
    - `intentHash` string, nullable, required
    - `clientOrderId` string, nullable, required
    - `side` 'buy' | 'sell' | 'null', nullable, required
    - `orderSize` number, nullable, required
    - `orderPrice` number, nullable, required
    - `venueStatus` string, nullable, required
    - `venueReportedFilledSize` number, nullable, required
    - `reconciliationState` 'submitted' | 'resting' | 'partially_filled' | 'fully_filled' | 'canceled' | 'venue_canceled' | 'rejected' | 'unknown' | 'ambiguous', required
    - `filledSize` number, required
    - `filledNotional` number, required
    - `avgFillPrice` number, nullable, required
    - `venueFee` number, required
    - `venueFeeToken` string, nullable, required
    - `fillCount` integer, required
    - `terminal` boolean, required
    - `reason` string, nullable, required
    - `fills` FuturesReconciledFill[], required
      - `fillId` integer, required
      - `fillHash` string, required
      - `side` 'buy' | 'sell', required
      - `size` number, required
      - `price` number, required
      - `notional` number, required
      - `fee` number, required
      - `feeToken` string, required
      - `sizeRaw` string, nullable, required
      - `priceRaw` string, nullable, required
      - `feeRaw` string, nullable, required
      - `builderFeeRaw` string, nullable, required
      - `filledAt` integer, required: Unix milliseconds
    - `state` 'submitted' | 'resting' | 'partially_filled' | 'fully_filled' | 'canceled' | 'venue_canceled' | 'rejected' | 'unknown' | 'ambiguous', required
    - `evidence` FuturesOrderReconciliationEvidence, required
      - `accountOwner` string, required
      - `signerAddress` string, required
      - `perpDex` string, required
      - `coin` string, required
      - `orderId` integer, required
      - `intentHash` string, nullable, required
      - `clientOrderId` string, nullable, required
      - `side` 'buy' | 'sell' | 'null', nullable, required
      - `orderSize` number, nullable, required
      - `orderPrice` number, nullable, required
      - `venueStatus` string, nullable, required
      - `venueReportedFilledSize` number, nullable, required
      - `reconciliationState` 'submitted' | 'resting' | 'partially_filled' | 'fully_filled' | 'canceled' | 'venue_canceled' | 'rejected' | 'unknown' | 'ambiguous', required
      - `filledSize` number, required
      - `filledNotional` number, required
      - `avgFillPrice` number, nullable, required
      - `venueFee` number, required
      - `venueFeeToken` string, nullable, required
      - `fillCount` integer, required
      - `terminal` boolean, required
      - `reason` string, nullable, required
      - `fills` FuturesReconciledFill[], required
        - `fillId` integer, required
        - `fillHash` string, required
        - `side` 'buy' | 'sell', required
        - `size` number, required
        - `price` number, required
        - `notional` number, required
        - `fee` number, required
        - `feeToken` string, required
        - `sizeRaw` string, nullable, required
        - `priceRaw` string, nullable, required
        - `feeRaw` string, nullable, required
        - `builderFeeRaw` string, nullable, required
        - `filledAt` integer, required: Unix milliseconds
  - `boundedReconciliation` BoundedFuturesReconciliation[]: Optional; omitted when no durable bounded actions match. An accepted reservation is not final venue cancellation.
    - `actionId` string, uuid, required
    - `result` union, required
      - BoundedFuturesReservation: Durable reservation row returned by FuturesPolicyService; not proof of execution, final cancellation or revenue
        - `id` string, uuid, required
        - `grant_id` string, uuid, required
        - `action_id` string, uuid, required
        - `network` 'mainnet' | 'testnet', required
        - `account_address` string, required
        - `coin` string, required
        - `intent_hash` string, required
        - `signed_action_hash` string, required
        - `venue_order_id` integer, nullable, required
        - `status` 'submitted' | 'accepted' | 'held_ambiguous' | 'reconciled' | 'released', required
        - `dispatched_at` string, date-time, required
        - `scope` 'futures.open' | 'futures.reduce' | 'futures.close' | 'futures.cancel' | 'futures.protective_order'
        - `venue_nonce` integer
        - `requested_notional_usd` union
          - number
          - string
        - `new_risk_usd` union
          - number
          - string
        - `risk_reducing` boolean
        - `expires_at` string, date-time
        - `created_at` string, date-time
        - `updated_at` string, date-time
        - `evidence` object, nullable
        - `cancel_target_evidence` object
      - object
        - `bounded` false, required
  - `builderFees` FuturesBuilderFeeReconciliation, required
    - `state` 'exact' | 'absent' | 'ambiguous' | 'unavailable', required
    - `builderFeeTotal` string, nullable, required
    - `fillCountWithBuilderFee` integer, required
    - `feeToken` string, nullable, required
    - `venueTotal` string, nullable, required
    - `nonBuilderVenueFee` string, nullable, required
    - `recipient` string, nullable, required
    - `signedTenthsBps` string, nullable, required
    - `reason` string, nullable, required
    - `fills` FuturesBuilderFeeFill[], required
      - `fillId` integer, required
      - `fillHash` string, required
      - `observedBuilderFee` string, nullable, required
      - `expectedBuilderFee` string, nullable, required
      - `builderFeeToken` string, nullable, required
      - `nonBuilderVenueFee` string, nullable, required
      - `state` 'exact' | 'absent' | 'ambiguous' | 'unavailable', required
      - `reason` string, nullable, required
  - `durableEvidence` ReconcileOrderDurableEvidence, required
    - `recorded` true, required
    - `record` object, nullable
    - `note` string, required
  - `evidenceSources` object, required
    - `orderStatus` 'hyperliquid_order_status', required
    - `fills` 'hyperliquid_user_fills', required
    - `methodology` 'direct_venue_evidence_only', required
    - `balanceDeltasUsed` false, required
  - `timestamp` integer, required: Unix milliseconds

## Other responses

- `400`: Invalid input or signer/account authority relationship
- `402`: Commercial API capacity payment required; payment is not execution authority
- `409`: controlActionId does not identify one unique durable action for this account, network and market; no liability released
- `413`: Request body exceeds 1 MB
- `429`: API rate limit exceeded
- `502`: Reconciliation unavailable; no execution or liability release inferred
- `503`: Venue evidence or durable reconciliation unavailable; inspect durableEvidence before claiming persistence, and never resubmit automatically

---

[API](https://skmtc.dev/farmdash/apis/farmdash-agent-api.md) · [All operations](https://skmtc.dev/farmdash/apis/farmdash-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/farmdash/apis/farmdash-agent-api/revisions/96310281f58c?raw)