# Automations

An automation is a task the agent runs on its own: on a schedule, when a condition becomes
true (for example a price crossing a level), or when your system sends it an event. Users
create and edit automations by asking the agent in a conversation; the API lets you list them, show
them, pause, resume and delete them, and send them events. There is no direct route to create or edit
one, and none to run one on demand: an automation runs only on its own schedule, condition or
events.

An automation never gets permission to move money just by running. A trade it proposes needs
the user's approval, unless the user approved limits for it when it was created: then its
scheduled runs can trade within those limits. Those limits can include paying out to
destinations the user approved; a run can never pay any other.

For new automations with approved NEAR Intents trading limits, entries can run only at a set
time, on an interval or calendar schedule, or when a 1Click token-price reading updates
(`at`, `interval`, `calendar`, `reader_update`). Entry conditions and price-update
wakes must use `oneclick.token_price` for the first entry swap's pinned input/output
pair; tokens used only by a later action cannot trigger an entry. Unused readers
may name other tokens pinned by approved actions. The only non-1Click exception
is the reviewed push-only exit pair below. Events, other readers and unpinned tokens
are refused before approval. A schedule with
no readers and an always-true condition is allowed. Automations without a contract
keep their existing source and event support, but gain no permission to spend.

The agent's creation tool reports an unsupported contract trigger with
`status: "failed"` and `error.code: "invalid_input"`. Its diagnostic names the refused
field and includes a message beginning `contract_trigger_unverifiable`. The consent
check independently refuses it as `invalid_input` with the same message prefix;
no approval is opened. There is no separate automation creation endpoint.

For an automation with trading limits, Fin checks each firing against a **1Click
signed dry quote**, not just a saved price reading. Price-based entries use the
quote's exact USD-per-token ratios for the first selected swap's pinned input and
output tokens; a condition requiring another token cannot authorize a trade.
The quote uses the approved exact-input quantity, or one whole input token for
other quantity rules. Fin independently checks the signature, pair, amount and
condition before allowing that firing to trade. Both checks use the same signed
numbers, with **no tolerance band**.

Clock-only entries that read no price and have no reader-update wake use only
1Click's signed timestamp. A payout-only automation obtains a dry reference
quote for one canonical USDC → wNEAR; this moves no funds, adds no action and
does not price the approved payout. Its approved payout amount and recipient
remain unchanged. Price-based entries and exits still require their exact quoted
pair and amount.

Fin's trusted clock decides freshness: the signed quote must be no more
than 30 seconds old or 5 seconds ahead. Scheduled checks must name a real slot of
the saved schedule and be within 60 seconds of both that clock and the signed
quote timestamp. Periodic exits likewise require a real slot of their saved interval.
A 1Click quote outage, stale quote or temporary sealing conflict leaves the check
unconsumed for a later retry; none can authorize a trade. Invalid or nonmatching
quotes may leave a refused proposal, but no permission to trade.
These checks also apply to already saved contract-backed automations, without
changing automations that have no trading contract.

For a “becomes true” trigger, Fin independently verifies that the condition holds
now, not the entire history of its transition. The scheduler still tracks that
history; Fin separately enforces the approved once-only/run-count/cooldown bounds
and financial limits. Entry limits do not disarm position exits.


A schedule like "every day at 9am" is read in the time zone you send with that message in
`context.timeZone` (see [Start a run](/api-reference/runs/start)); without one, the agent asks
the user. The automation keeps that zone, through daylight saving too, even after the user
travels. A user who moves can ask the agent to edit the saved automation's zone in chat;
the change takes effect only after approval of the exact resulting definition.
Send `context.country` from your server's edge geolocation with every message too, including
requests to create a tokenized-stock automation. Purchases require an allowed country and an
operator-enabled `tokenized_stocks` flag; these assets can only be sold, never withdrawn or
sent. See [Tokenized stocks](/concepts#tokenized-stocks).

Examples use the variables from the [quickstart](/quickstart).

## Deadlines and missed runs

Every automation has a deadline, `rule.maxDeliveryLatenessSeconds`, from 1 to 86,400 seconds: how
late after it fires a run may start and sign. A schedule's deadline can't be longer than the shortest
gap between its runs; the agent chooses it from how time-sensitive the request is. A contract's
signed windows follow from the deadline, so the approval shows one set of terms and nothing is
chosen twice.

`missedRun` on an automation, `skip` or `ask`, is what happens to a run that can't go through before
its deadline. `skip` counts the run, keeps the schedule and tells the owner once per streak of
failures. `ask` pauses the automation and asks the owner, with `waitingForOwner` set. A fault on Fin's
side keeps the schedule whichever is chosen, unless it took a rule's last run. The agent
chooses it, and an owner can change it by asking in chat. It reads `ask` when none was chosen. A
failure only the owner can fix, like an empty wallet, pauses whichever is chosen.

## Perps automations

An automation can also act on the agent's own Hyperliquid account (see
[Open a perps account](/wallet-transfers#open-a-perps-account)): reduce or close a position, or
add margin to the account, when a condition Hyperliquid's own orders cannot express holds.
A fixed take-profit, stop-loss or trailing stop stays a native order on the position
(`perps_order_place`, see [Approve perps orders](/wallet-transfers#approve-perps-orders));
an automation is for conditions such as the funding rate, open interest, the margin ratio,
distance to liquidation, unrealized PnL or a time.

Choose the two reviewed recipes for the contract coin's dex. Main-dex coins use
`hyperliquid.market` / `hyperliquid.position` with `{ "coin": "BTC" }` (or its listed
main-dex name). trade.xyz coins use `trade_xyz.market` / `trade_xyz.position` with
`{ "coin": "xyz:TSLA" }` (or its full listed `xyz:` name). Never mix source families.
Take both the full coin and global asset id exactly from `perps_markets`.

- `hyperliquid.market` or `trade_xyz.market` (public): `markPriceUsd`, `oraclePriceUsd`, `midPriceUsd` (optional),
  `fundingRatePerHour` (signed), `openInterestAsset`, `openInterestUsd`, `dayVolumeUsd` and
  `dayChangePercent` (signed).
- `hyperliquid.position` or `trade_xyz.position` (the agent's own account): `positionSizeAsset` (signed; `0` when
  flat), `side` (`long`, `short` or `flat`), `entryPriceUsd`, `markPriceUsd`,
  `liquidationPriceUsd` and `liquidationDistancePercent` (optional), `unrealizedPnlUsd`,
  `returnOnEquityPercent`, `marginUsedUsd`, `leverage`, `accountValueUsd`,
  `maintenanceMarginUsd`, `marginRatioPercent` and `spotUsdcAvailable`.

Values are exact decimal strings with the units the source catalog lists. All are polled
snapshots; Hyperliquid gives no observation time, so each reading is stamped when fetched.
Account value, maintenance margin and margin ratio belong to the selected dex;
`spotUsdcAvailable` is shared account-wide collateral, not additive across dexes.
Existing main-dex source bindings keep their identities and require no migration.

The money it may move is a `perps_automation` contract the user approves (and signs, as for
any automation with trading limits) when the automation is created:

```json
{
  "type": "perps_automation",
  "coin": "BTC",
  "asset": 0,
  "position": "long",
  "action": { "kind": "reduce", "fractionBps": 5000, "maxSlippageBps": 100 },
  "maxExecutions": 3,
  "validUntil": "2026-11-16T00:00:00.000Z"
}
```

- `open` (`{ "kind": "open", "notionalUsd": "200", "leverage": 3, "marginMode": "cross",
  "maxSlippageBps": 100, "takeProfitPercent": "10", "stopLossPercent": "5" }`) opens the named
  position with a market order of `notionalUsd` at the mark when it fires (at most two decimal
  places), sized in the coin by rounding down to the market's size step, at exactly that leverage
  and margin mode, no worse than `maxSlippageBps` (at most 500) from the mark. It acts only
  while the agent holds nothing on the coin: it never adds to or flips a position, so a repeating
  open enters again only after the position is closed. `takeProfitPercent` and
  `stopLossPercent` (above 0 and below 100, or `null`) become native Hyperliquid exits that far
  from the mark it opened at, each filling within `maxSlippageBps` of its trigger.
  Fin checks the position again before signing and before sending either the leverage setting
  or entry; an unanswered opening on that market blocks another automated open. These venue
  reads are not an atomic flat-only condition at Hyperliquid, so avoid overlapping resting
  entries on the same coin.
- `reduce` closes `fractionBps` of the named position (`10000` closes it all) with a
  reduce-only market order no worse than `maxSlippageBps` (at most 500) from the mark.
  Nothing happens while the agent is flat or holds the other side.
- `add_margin` (`{ "kind": "add_margin", "amountRaw": "25000000", "maxValueLossBps": 100 }`)
  moves exactly that USDC (six decimals) from the agent wallet into the perps account, losing
  at most `maxValueLossBps` (at most 300) to fees. It too acts only while the agent holds the
  named position: nothing happens while the agent is flat or holds the other side.

Each firing that acts uses one of `maxExecutions`; the
automation ends when they are used or `validUntil` passes, and deleting it revokes the
contract. Its rule may read only those two recipes for the contract's own coin, with
`at`, `interval`, `calendar` or `reader_update` wakes; anything else is refused with
`contract_trigger_unverifiable` before approval. An entry at a fixed price is a resting limit
order, not an automation.

A saved observation never moves money by itself. When the rule fires, Fin's policy worker
reads Hyperliquid itself, checks the rule again on what it read, and computes the exact order
or funding from the contract and that state; the run submits exactly that call and nothing
else, and no other perps write is available to it. A reduce is an exit and is never gated.
Opening a position or adding margin needs the user's `perps` feature and an allowed region: the
latest `context.perpsAllowed` your server reported on one of the user's runs must be `true` and at
most 7 days old, because no one is present when it fires. Otherwise the firing is refused with
`not_available_in_region` and nothing moves; report `context.perpsAllowed` on every run so it
stays current.

`Automation.contract.terms` returns the approved contract; narrow on `terms.type`. `spendUsed` is
what counts against the cap, in-flight amounts included; show `settledSpend` for what the automation
actually spent. For a perps or Polymarket automation both are empty and `executionsUsed` counts the
firings that acted.
Each run's `perps` field is what that firing did on Hyperliquid: `{ kind: "order" }` with the
exact `order` it placed (reduce-only for a `reduce`, opening for an `open`) and Hyperliquid's
`outcome` (each placement's fill), or
`{ kind: "margin" }` with the `transfer` it moved and how it ended. `outcome` is `null` while the
order or transfer is still under way; the run never sends it twice.

## Polymarket automations

An automation can trade one Polymarket outcome on its own odds: "buy $50 of Yes when its chance
drops below 30%", "sell half my Yes once it is above 70%". The user approves a
`prediction_automation` contract when the automation is created; it is never edited (archive it
and create another):

```json
{
  "type": "prediction_automation",
  "market": {
    "marketId": "12345",
    "conditionId": "0x…",
    "assetId": "123456789…",
    "marketQuestion": "Will the Fed cut rates in December?",
    "outcome": "Yes"
  },
  "action": { "kind": "buy", "amountUsdDecimal": "50", "maxPriceUsdDecimal": "0.32", "maxFeeUsdDecimal": "1" },
  "maxExecutions": 3,
  "validUntil": "2026-12-31T00:00:00.000Z"
}
```

- `buy` places an immediate order of `amountUsdDecimal` pUSD (to the cent) paying no more than
  `maxPriceUsdDecimal` a share; what the book does not fill at once is cancelled. Every firing
  places the same order, so it spends at most `maxExecutions` × `amountUsdDecimal` before fees.
- `sell` (`{ "kind": "sell", "fractionBps": 5000, "minPriceUsdDecimal": "0.7", "maxFeeUsdDecimal": "1" }`)
  sells that share of the agent's holding of the outcome at no less than `minPriceUsdDecimal`;
  nothing happens while it holds none.

`market` is copied exactly from the agent's market lookup; a market's Yes and No are different
`assetId`s. The rule may read only polled `polymarket.outcome` readers of that same outcome and
compare only `bestBidUsdDecimal`, `bestAskUsdDecimal` or `midpointUsdDecimal`, with `at`,
`interval`, `calendar` or `reader_update` wakes; anything else is refused with
`contract_trigger_unverifiable` before approval. When it fires, Fin's policy worker reads the
order book itself, checks the rule again on what it read and places exactly the order the
contract implies; a closed or resolved market has no book, so nothing trades. It needs the
user's `prediction` feature and a ready Polymarket account. Each run's order appears among the
user's Polymarket orders, and `executionsUsed` counts the firings whose order was signed.

## Cross-venue triggers

An automation that trades on one venue can be timed by what happens on another: "buy 200 USDC of
BTC once Fed-cut odds pass 70%", "sell my Yes if BTC's Hyperliquid mark falls below 90,000",
"close half my BTC long when Fed-cut odds pass 70%". Any trading contract's rule may add a polled
reader of another venue and compare it in the entry condition only:

| Reader | Compared by |
|---|---|
| `polymarket.outcome` | `bestBidUsdDecimal`, `bestAskUsdDecimal`, `midpointUsdDecimal` |
| `hyperliquid.market`, `trade_xyz.market` (any coin) | the market fields, such as `markPriceUsd` |
| `oneclick.token_price` (any token; not for a NEAR Intents contract, whose 1Click readers are its own) | `priceUsdDecimal` |
| `jupiter.token_price` (any mint) | `priceUsdDecimal` |

Such a reader is woken by nothing: the rule uses an `at`, `interval` or `calendar` wake. A
`reader_update` wake on it, a `rule.exit` that reads it, another field, a push feed or a webhook is
refused with `contract_trigger_unverifiable` before approval. The contract still says exactly
what is traded, with what bounds and how many times; before it signs, Fin's policy worker reads the
other venue itself and checks the condition again, and a NEAR Intents buy is still priced by
1Click's signed quote.

## Edit through chat

Send the correction as an ordinary message, such as “move my daily report to 10 AM
in America/New_York.” The agent searches the owner's automations and asks when the
target is ambiguous, reads the complete editable definition and snapshot, then proposes
`automations_edit`. The approval shows the exact target snapshot, current definition,
requested differences and complete resulting definition. No definition is reconstructed
from a readable summary. Every edit needs exact approval; if either definition permits
financial actions, even a rename or removing those permissions needs a new owner signature
through the existing wallet authorization flow.

Unchanged caps/expiry retain prior spent, used and reserved allowance; the approval
shows resulting remaining allowance, not a renewed budget. Open positions needing their
approved exits and unresolved financial operations block editing. A stale proposal needs
a fresh read and approval. Editing keeps the automation ID/history and paused state,
does not clear an operator hold and cannot restore an archived automation.

A completed tool receipt names the committed `definitionVersion` and `activationEpoch`.
Render it from durable journal replay and refresh the same owner-scoped automation read
used by your detail page; never let a cached older version replace the receipt.
Old admitted runs retain their original version/evidence and signed effects still reconcile.
When `webhookSetupRequired` is true, obtain a new webhook key on Manage and update
the sender; no secret is returned to the agent. Commit is not proof of source health,
a next firing, policy acknowledgement or settled money movement.


## List and read automations

```bash
curl --fail-with-body -sS "${FIN_AUTH[@]}" \
  "$FIN_BASE_URL/v1/users/$FIN_USER_ID/automations?filter=current&limit=20"
```

`filter=current` shows running and paused automations and hides deleted ones; `enabled`,
`paused` and `deleted` narrow further, and `all` (the default) includes everything. `query`
searches names and instructions.

[Get an automation](/api-reference/automations/get) returns everything about one:

- `name`, `prompt` (the instructions the agent follows) and `summary`, a sentence describing
  when it runs, ready to show;
- `definitionVersion`, the committed saved-definition revision. This server always returns it;
  the SDK keeps it optional for earlier servers.
  Until a read proves a version at least as new as an edit receipt, keep that receipt visible
  rather than replacing it with stale state;
- `enabled`, `nextFireAt` and `monitoring`, which reports whether its data sources are healthy
  and what the condition last evaluated to. A news exit (`rule.news`) has no sources or webhook
  of its own: its `monitoring.webhook` is always `null`, and its `monitoring.status` is
  `healthy` while Fin's news judge checks the news for it, or `unavailable` (with a `reason`
  saying news checks are paused) while news exits are off for the user. Never ask for a webhook
  key for one;
- `activeRun` and `latestRun`;
- `contract`, when the user approved trading limits for it: the limits, and how much of them
  has been used. `rule.exit` describes the position exits a contract may carry: how often the
  agent re-checks them and the pinned pair used for their signed quote. For a
  contract automation, the asset reader names the exit action's pinned input token
  and the quote reader its pinned output token, both through `oneclick.token_price`.

New latency-sensitive position exits may also use fast price updates when enabled
for the user. `rule.exit.push.readers` names the supplementary asset and quote
readers: only `kraken.asset_price` or `consensus.asset_price`, with
`delivery: "push"`. They must price each exit action's exact pinned input and
output tokens respectively, not just other tokens in the approved actions.
They may be referenced only by `rule.exit.push.readers`, never in the entry
condition at any depth or in either operand, or by a `reader_update` wake.
`rule.exit.intervalSeconds` remains the periodic 1Click check interval.
Existing automations keep their approved monitoring plan. Users do not need to
choose a transport or configure a price-feed connection.

Show both the saved plan and `monitoring.sources`. Saving alone does not mean
updates are arriving. The agent saves an automation only on data sources this
deployment serves: a shared source it does not offer is listed with
`availability.status: "unavailable"` in [List automation data sources](/api-reference/automations/list-sources),
and the agent picks another that reads the same fact or tells the user why it can't.
A plan blocked on the user's own step, such as creating their agent wallet, is saved
with `status: "needs_connection"` and starts monitoring once they finish it and resume
the automation. An unavailable or stale supplementary feed reports
`monitoring.status: "stale"` with a reason explaining the periodic fallback;
an unavailable required source reports `"unavailable"`. A fallback check needs
a fresh signed 1Click quote. Fast sources are public venue prices — preferably
the median of Kraken and Coinbase, which publishes nothing while the venues
disagree by more than 1% — and can differ from 1Click. Coinbase participates in
consensus; it is not a separate reader operation.
These feeds are **wake hints only** for contract-backed exits: they decide when
an exit gets checked. The guard uses the signed input USD-per-token price divided
by the signed output USD-per-token price: a **fee-neutral** output-token-per-input-token
rate, not the net executable amounts or catalog prices. Fees and spread must not
produce a false stop-loss at an unchanged market price. Fin independently recomputes
this automation's own position and approved fraction before authorizing the firing,
and checks its plan against that same verified rate. The trigger quote's amount is not
capped by wallet balance; the actual sale still is. Fresh execution quotes and
ordinary balance and loss limits remain required. A brief move, reconnect gap or
particular execution delay is not guaranteed to be covered.

## Solana tokens

An automation can watch a Solana token's price with the `jupiter.token_price` reader, which
names the token by its mint and reads Jupiter's Price v3 at most every 30 seconds. Without
trading limits, such an automation is an **alert, not an automatic exit**: when it fires, the
agent tells the user and proposes the sale as a `solana_sell` approval that waits for them. The
run never buys and never sells on its own.

The user can also approve standing limits for a Solana trade when the automation is created:
its `contract.terms.type` is then `solana_buy` or `solana_sell`. Each firing makes exactly the
approved trade, never another token, amount or loss bound:

- `solana_buy` buys the token named by its mint with the approved amount, at least 5 USDC when
  paid in USDC. Creating one needs the user's `solana` flag, as any Solana buy does.
- `solana_sell` sells a share (`amount.kind: "fraction"`) of what the agent's Solana account holds
  of the token when the firing runs, for USDC on NEAR (`receive: "usdc"`). It never sells an
  exact amount the account may no longer hold. Selling is never gated by the flag.
- `maxExecutions` and `validUntil` bound how many firings may trade and until when.
  `contract.executionsUsed` counts the firings that started trading, settled or not.

Such an automation can fire only on a schedule (`at`, `interval`, `calendar`) or when its own
`jupiter.token_price` reading of the traded mint updates (`reader_update`); its condition may
compare only that reader's `priceUsdDecimal`. A take-profit or a stop-loss is a `solana_sell`
whose condition reads the price, so `rule.exit` is refused, as are event wakes, other readers and
another token's price, before any approval opens, with a message beginning
`contract_trigger_unverifiable`. So is a `solana_buy` that wakes on `reader_update` and compares
no price: it would buy at every reading and use up its executions within minutes. Give it a price
condition, or wake it on a schedule.

Before a firing may trade, Fin's policy service checks it itself. A scheduled firing must name a
real slot of the saved schedule, within 60 seconds of Fin's own clock. A price condition is
re-evaluated on Fin's own read of Jupiter's Price v3 for the traded mint, with no tolerance: the
price must have last changed within about ten minutes of Fin's own Solana network reading. The
scheduler's reading only proposes the firing. If Fin's read disagrees, is stale, or Jupiter or
the Solana network does not answer at that moment, that firing's run cannot trade, and it still
counts as the rule's firing: a once-only rule does not fire again, while a repeating rule's next
firing is checked afresh.

Read a standing trade's financial result on the automation run's `solana` field. It names the
activity item's `id`, `kind` (`buy` or `sell`), exact admitted `request`, and observed `outcome`.
It is null or absent before the run acts and for other automations; `outcome` is null while no
result is recorded. A `pending` result still needs observation even when `runStatus` says
`completed`. A `partial` result can leave SOL in the Solana account; show only the amounts the
outcome records. A provider refund status alone does not prove the refunded amount. This also
appears on `activeRun` and `latestRun`, so the list and run detail can show the same financial
state. Solana trades are not returned by the Intents wallet-trades listing.

A standing Solana automation cannot be edited: delete it and ask the agent for a new one with
the terms the user wants.

## Pause, resume and delete

```bash
FIN_AUTOMATION_URL="$FIN_BASE_URL/v1/users/$FIN_USER_ID/automations/$FIN_AUTOMATION_ID"
curl --fail-with-body -sS "${FIN_AUTH[@]}" -X POST "$FIN_AUTOMATION_URL/pause"
curl --fail-with-body -sS "${FIN_AUTH[@]}" -X POST "$FIN_AUTOMATION_URL/resume"
curl --fail-with-body -sS "${FIN_AUTH[@]}" -X DELETE "$FIN_AUTOMATION_URL"
```

Pausing stops the automation and cancels runs that were waiting to start; runs already going
finish, but a run that started before the pause can't trade. Deleting stops it for good, and its
history stays readable. If the automation has trading limits, pausing keeps them: resuming
carries on under the limits the user already approved, with no new signature. Resume is refused
(`409 automation_invalid`) once those limits have been revoked, or when a data source it reads
is no longer offered; the user then sets the automation up again by asking the agent. Resuming
an automation whose source was waiting on the user's own step is how it starts monitoring.

Fin pauses an automation itself when a run can't go on and only its owner can decide: its wallet
can't pay, it can't run as written, or a run missed its deadline with `missedRun: "ask"`. Under `ask`,
a failure that took a rule's last run pauses too, for every kind of automation. Fin also pauses an
automation whose data source can no longer be read until its owner resumes it, such as one whose
source a release changed, once it has gone fifteen minutes without a reading. `enabled` reads
`false` and `waitingForOwner` names what the automation needs (`action`: `add_funds`,
`edit_automation`, `decide` or `resume`), why it stopped (`reason`), the run it stopped at (`runId`)
and when (`since`). No run stops a `resume` pause, so its `runId` is `null` and its `reason` reads
`unavailable`. The owner gets one `waiting` notification; nothing retries or fires until they
answer, and fin never moves money over a pause. Only the owner ends one:

- **Resume** starts it again from its next slot and runs nothing it missed. For `resume`, it reads
  the data source again as it is now. The run it paused over goes back to the run limit. Pass
  `countMissedRun=true` when the owner lets that run go, so it counts; a rule that runs once then
  ends. A value that isn't a yes or a no (`true`, `false`, `1`, `0` and the like), or any parameter
  it doesn't know, answers `400`. Without a pause the parameter changes nothing.
- **An edit through the agent** answers it: the run goes back, `waitingForOwner` clears and the
  automation stays paused until it is resumed.
- **Delete** stops it, and the run counts.

`runCount` leaves out the run it waits over until the owner chooses. `skippedRunCount` says how many
runs were skipped: they failed, counted and left the schedule as it was. The `waiting` notification
reads `status: "done"` once the pause is over.

An operator can also hold an automation. A held automation answers `409 automation_held`
until the operator releases it; the user can't lift a hold.

Every creation, pause, resume and deletion also appears in [List activity](/api-reference/activity/list)
as an item of `kind: "automation"`. An automation an operator retires, or one that finishes on
its own, shows there as `deleted`, the way Get an automation reports it.
Edits are retained privately and shown in their chat receipt and automation detail, not in this
unchanged `/v1` activity contract. The server excludes `edited` rows before limits and cursor
pagination, so they do not consume visible pages or affect their item counts.

## See what it did

```bash
curl --fail-with-body -sS "${FIN_AUTH[@]}" \
  "$FIN_BASE_URL/v1/users/$FIN_USER_ID/automations/$FIN_AUTOMATION_ID/runs?limit=20"
```

Each automation run records when and why it happened, whether the agent ran or it was skipped
(for example because the previous run hadn't finished), the agent run it started and any
approvals waiting. Its `selection` says what the firing ran: an entry firing runs the
automation's buys in order, while an exit firing runs one take-profit or stop-loss sale of what
the automation itself bought. Each one runs in a fresh conversation. A finished run doesn't
prove a trade settled: read the trade under [Deposits, withdrawals and trades](/wallet-transfers#trades).

`runNumber` says which of the automation's own runs this is, counting from 1, the number its run
limit counts. It is `null` for a run that isn't a firing of its own, such as an exit selling a
position. `deliverySequence` runs across every automation, so use it only to page, never to show.
On the automation, `runCount` is how many numbered runs it has had (leaving out one it waits on its owner over) and `harvestCount` how many
times it has harvested a gain, so you never need to infer either from `latestRun`.

Treat `state` as a closed list that will grow. A started run reads `accepted` while it works and
`retrying` while it waits to try again before `deadlineAt`, the latest it may still try: a trade
a temporary outage refused before anything of it was planned or signed repeats until then and tells nobody until
it ends. It then reads
how it ended: `succeeded`, `partial`, `failed`, or `uncertain` when money may have moved and how it
ended isn't known yet. A run that went through after trying again reads `succeeded` with `attempts`
above 1. A `failed` or `partial` run's `reason` is one of `unavailable`, `insufficient_funds`,
`empty_input` (there was nothing of it to sell), `quote_rejected`, `not_authorized`, `not_executed` or `condition_passed`, the last when the rule's
condition stopped holding while it waited.

To draw what an automation watches, read its sources over time:

```bash
curl --fail-with-body -sS "${FIN_AUTH[@]}" \
  "$FIN_BASE_URL/v1/users/$FIN_USER_ID/automations/$FIN_AUTOMATION_ID/readings"
```

[List automation readings](/api-reference/automations/list-readings) answers one entry per reader
in the rule: its `latest` good reading (the whole snapshot, for example a perps position's size,
mark and liquidation price) and, for each field the rule's condition compares, the values over the
window as exact decimal strings, at most 240 points, oldest first. The window is the last 30 days
unless you pass `since` and `until`, at most 90 days apart; plot the rule's thresholds over it and
each run's `evidence.evaluatedAt` on it.

## Send it events

An automation without a contract can run on incoming events and has its own webhook.
New contract automations cannot use event wakes. Create the event automation's secret:

```bash
curl --fail-with-body -sS "${FIN_AUTH[@]}" \
  -X POST "$FIN_BASE_URL/v1/users/$FIN_USER_ID/automations/$FIN_AUTOMATION_ID/rotate-webhook-secret" \
  > webhook.json
FIN_WEBHOOK_PATH=$(jq -er '.path' webhook.json)
FIN_WEBHOOK_SECRET=$(jq -er '.secret' webhook.json)
```

The secret is shown once. Give it only to the system that sends the events. Rotating again
replaces it at once, and pausing, resuming or deleting the automation also retires it. An
automation that doesn't run on events answers `409 automation_has_no_webhook`, and so does a news
exit: only Fin's news judge delivers its `news.judged` event.

Your system then posts each event to the returned path with the secret in `X-Automation-Key`
(not your API key or a session token):

```bash
curl --fail-with-body -sS -X POST "$FIN_BASE_URL$FIN_WEBHOOK_PATH" \
  -H "X-Automation-Key: $FIN_WEBHOOK_SECRET" -H 'Content-Type: application/json' \
  -d "$(jq -n --arg at "$(date -u +'%Y-%m-%dT%H:%M:%SZ')" \
    '{id:"invoice-123",type:"invoice.paid",occurredAt:$at,data:{paid:true}}')"
```

| Answer | Meaning |
| --- | --- |
| `202` | Recorded. Whether the automation runs depends on its condition. |
| `200` | You already sent this event `id`; nothing new happened. Resending is safe. |
| `400` | The event is malformed, too old (over 5 minutes) or too far in the future (over 5 seconds). |
| `401` | Wrong or retired secret. |
| `409` | This event `id` was already sent with different content. |
| `410` | The automation has finished for good. |
| `429` | More than 60 events a minute; wait for `Retry-After`. |

Events are at most 16 KiB. A recorded event doesn't mean the condition matched or that the
agent ran; see the automation's runs for that.

## Preview historical behavior

Call `fin.user({ userId, token }).automations.backtest(input)` to replay a draft definition or
one saved automation over a past window. Select the hypothetical funding assumption:

- Set `contributeInputs: true` and `initialHoldings: []` for independent, fixed-size entry
  swaps. Each successful modeled entry receives its full input token debit as an external
  contribution at fill time. The account starts empty; skipped, refused and unfilled entries
  add no funds. Later entries receive new contributions even if earlier exit proceeds remain.
  Exits only spend positions accumulated by the replay. Percentage/all-balance entries,
  portfolio-value conditions and recycling entry templates require a starting portfolio instead.
- Omit `funding` and `contributeInputs` and supply exact `initialHoldings` (token identity, decimals and raw quantity)
  for a finite portfolio, percentage sizing or reinvestment. Starting assets are explicit
  assumptions, including an intentionally empty portfolio; live balances are never imported.
- Set `funding: "strategy_budget"` with `initialHoldings: []` to retain finite upfront funding.
  It sets aside entry sizes times maximum runs at opening historical prices, or explicit
  total-input token caps. Uncapped balance-relative entries receive a disclosed $1,000 per
  input token. Read the resolved `scenario.initialHoldings` and limitations. Later price changes
  can exhaust that finite budget. This is not a contribution-funded replay.

For contribution-funded reports, retain `contributions` beside `trades`: each row identifies
the input token, raw quantity, action index, fill time and its USD value at that time. Profit
excludes those funds: `endingValueUsdDecimal - startingValueUsdDecimal -
contributedValueUsdDecimal`. Each equity point includes cumulative contributed value so the
chart can make the same subtraction. The percentage is profit divided by total starting and
contributed capital, not an annualized or time-weighted return. The no-trade comparison keeps
the same contributed input tokens instead of swapping them; drawdown is adjusted for incoming
capital using a reporting index rounded down at each mark to 36 decimal places, with exact
money and trade arithmetic. If that index cannot represent a positive value, the report is
incomplete with `performance_precision_limit`, without final metrics. Starting-portfolio and
finite-budget reports retain their existing response shape.
`report_value_limit` means modeled values exceeded the report's supported bounds; the response
retains its scenario identity without financial metrics or unrepresentable detailed values.
`starting_portfolio_required` means the selected contribution policy cannot size or finance
that strategy; retry with explicit holdings and neither automatic funding option. Never replace that outcome with
a zero-profit claim. Only `estimated` reports with metrics support financial performance.

All scenarios retain their run/spend limits regardless of the historical window. Trade amounts
are frozen at admission and filled at a later observation; input prices can change before fill,
so a fixed-dollar instruction's contributed USD value can differ from its admission value.
These holdings and contributions never reconstruct the user's historical wallet.
Choose `preserved` timing to require compatible observations or
`sampled` to accept explicitly listed timing changes, plus hourly/daily resolution and modeled
cost basis points. The report identifies the scenario, data hash, observation assumptions and
limits. Show performance only for `status: "estimated"` with non-null metrics; incomplete,
unavailable and trigger-only results must retain their reason and limitations. A replay grants
no approval or standing consent, and changes no automation.

Two definitions answer `status: "unavailable"` before any history is read. A contract other
than a NEAR Intents transfer, such as a perps automation or a standing Solana buy or sell, gives
`reason: "unsupported_contract"`. A rule that watches a Solana token's price
(`jupiter.token_price`) gives `reason: "unsupported_source"`, because no historical source
covers that price.

Historical collection can take up to five minutes. For SDK calls, configure a dedicated client
with `timeoutMs: 310_000` and pass an `AbortSignal` so leaving the preview cancels collection.
Keep starting balances and the date window fixed while presenting a result; request a new replay
when any assumption changes. Retain `manifest.tokenMappings` with the report so its exact token
identities and CoinGecko price proxies stay visible beside the dataset hash.

Select `execution: "contract_terms"` only to hypothetically replay the concrete trade terms.
A standing contract bounds authority; it does not describe discretionary model choices. For a
prompt whose trades are unresolved, use `execution: "triggers_only"` and present only trigger
counts, timing and data limitations. Never describe contract-term returns as a prediction of
what a discretionary agent would decide.
