Limit orders
Onchain escrow and fixed user payouts, with a dedicated Path resolver and pool-based triggers.
Read capabilities first
curl https://api.pathagg.xyz/api/v1/orders/capabilitiesSupported order models
| Kind | Behavior |
|---|---|
| take-profit | Receive the fixed sell entitlement at the signed limit; execution surplus goes to Path. |
| stop-loss | Latch a downward pool-history trigger, then sell only if the separate minimum execution price is achievable. |
| buy-dip | Receive the fixed base-token allocation at the maximum signed buy price. |
| buy-pump | Latch an upward pool-history trigger, then buy within the signed maximum execution price. |
| oco | One escrow, two exit conditions; a successful fill atomically closes the other branch. |
| buy-oco | A full entry escrows the user allocation for exits; entry surplus is transferred to Path separately. |
| trailing-stop | A stop follows the peak observed through onchain updates. |
Every leg fills in full. There is no DCA or partial fill per leg. A trigger being observed does not guarantee a fill: gas, route liquidity, pool-history availability and settlement checks still apply. Once latched, stop execution uses its frozen payout without requiring the reference to remain fresh. Trailing orders track observed peaks, not every market high.
Escrow and execution prices
Limit v2 creation deposits the input into PathLimitSettlement. Onchain state controls ownership, escrow, trigger status and cancellation. Cancelling before a Buy → OCO entry returns the original quote token; cancelling after entry returns the acquired base token.
PathMarketReader reads qualified V2 volatile cumulative prices or V3 historical observations onchain. Source profiles pin the pool, time window, freshness, liquidity floor and total base exposure cap. Unsupported pool histories are not replaced by display prices. Stop triggers use pool history; executable full-size route output is still enforced by settlement. No Pyth or Chainlink key is required for v2.
User payout and resolver surplus
The user receives the reviewed fixed entitlement. All actual positive execution surplus goes to the immutable Path treasury. For example, a 100-token sell with a 1.1 limit pays the user 110 quote tokens; if the route actually returns 114, Path receives 4. The treasury cannot be selected by the caller.
Stop orders sign a trigger and a separate execution limit. Trailing orders sign a trailing distance, a limit offset up to 5%, and an optional absolute minimum; the payout freezes when the observed trigger is latched. A stop-limit can remain unfilled through a gap. Cancel returns the remaining escrow, with native refunds wrapped by default.
Settlement accounting exposes grossOutput, userReceived, nextEscrow and resolverSurplus. Quote surplus is only an estimate; actual balance changes determine final accounting. No admin function can withdraw user escrow.
The order API flow
- Read capabilities; strict Take Profit / Buy Dip do not need a pool reference.
- POST /api/v1/orders/preview; use the returned request, including clientNonce, marketId and policyHash, for review and creation.
- POST /api/v1/orders/create-transaction with {order, sender}; inspect exact approval and unsigned calldata.
- Approve, rebuild and sign after readiness and preflight checks pass. Preserve the nonce and transaction hash across reloads; /api/v1/orders/creation?owner=…&nonce=… recovers the created order.
- GET /api/v1/orders?owner=…&state=open to read current active orders.
- POST /api/v1/orders/{id}/cancel-transaction with {sender} for an unsigned owner cancellation.
- GET /api/v1/orders/{id}/events for canonical lifecycle history when the index is configured.
Order state comes from the contract. Transaction event pages use a separate reorg-aware journal and may lag by the configured confirmation delay. A displayed trigger does not mean an order filled.