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); 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.
Examples use the variables from the 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): 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); 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.marketortrade_xyz.market(public):markPriceUsd,oraclePriceUsd,midPriceUsd(optional),fundingRatePerHour(signed),openInterestAsset,openInterestUsd,dayVolumeUsdanddayChangePercent(signed).hyperliquid.positionortrade_xyz.position(the agent's own account):positionSizeAsset(signed;0when flat),side(long,shortorflat),entryPriceUsd,markPriceUsd,liquidationPriceUsdandliquidationDistancePercent(optional),unrealizedPnlUsd,returnOnEquityPercent,marginUsedUsd,leverage,accountValueUsd,maintenanceMarginUsd,marginRatioPercentandspotUsdcAvailable.
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:
{
"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 ofnotionalUsdat 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 thanmaxSlippageBps(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.takeProfitPercentandstopLossPercent(above 0 and below 100, ornull) become native Hyperliquid exits that far from the mark it opened at, each filling withinmaxSlippageBpsof 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.reduceclosesfractionBpsof the named position (10000closes it all) with a reduce-only market order no worse thanmaxSlippageBps(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 mostmaxValueLossBps(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):
{
"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"
}buyplaces an immediate order ofamountUsdDecimalpUSD (to the cent) paying no more thanmaxPriceUsdDecimala share; what the book does not fill at once is cancelled. Every firing places the same order, so it spends at mostmaxExecutions×amountUsdDecimalbefore 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 thanminPriceUsdDecimal; nothing happens while it holds none.
market is copied exactly from the agent's market lookup; a market's Yes and No are different assetIds. 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
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 returns everything about one:
name,prompt(the instructions the agent follows) andsummary, 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,nextFireAtandmonitoring, 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: itsmonitoring.webhookis alwaysnull, and itsmonitoring.statusishealthywhile Fin's news judge checks the news for it, orunavailable(with areasonsaying news checks are paused) while news exits are off for the user. Never ask for a webhook key for one;activeRunandlatestRun;contract, when the user approved trading limits for it: the limits, and how much of them has been used.rule.exitdescribes 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 throughoneclick.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, 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_buybuys the token named by its mint with the approved amount, at least 5 USDC when paid in USDC. Creating one needs the user'ssolanaflag, as any Solana buy does.solana_sellsells 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.maxExecutionsandvalidUntilbound how many firings may trade and until when.contract.executionsUsedcounts 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
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. PasscountMissedRun=truewhen 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,0and the like), or any parameter it doesn't know, answers400. Without a pause the parameter changes nothing. - An edit through the agent answers it: the run goes back,
waitingForOwnerclears 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 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
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.
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:
curl --fail-with-body -sS "${FIN_AUTH[@]}" \
"$FIN_BASE_URL/v1/users/$FIN_USER_ID/automations/$FIN_AUTOMATION_ID/readings"List automation 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:
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):
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: trueandinitialHoldings: []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
fundingandcontributeInputsand supply exactinitialHoldings(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"withinitialHoldings: []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 resolvedscenario.initialHoldingsand 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.