> ## Documentation Index > Fetch the complete documentation index at: https://docs.defiloops.com/llms.txt > Use this file to discover all available pages before exploring further. # Every tool > The full tool registry, with the descriptions the model actually reads. Generated from the tool registry at `465d7e1-dirty` — **36 tools**, exactly as the model is offered them. The description column is the description the model reads, verbatim: these are not documentation *about* the tools, they are the prompt. **5 of them spend money** and are marked ⚠. Those are withheld until somebody presses Start, and gated again on the way through. See [the tool server](/tools). ## Tools that spend ### `arm_schedule` ⚠ Put a schedule live NOW, rather than letting a chain arm it when the stage before it succeeds. From this moment it fires unattended and SPENDS REAL FUNDS every time. Prefer letting a chain arm it: that way nothing recurs until the setup it depends on actually worked. | argument | required | meaning | | ---------- | -------- | --------------- | | `schedule` | yes | the schedule id | ### `decide_firing` ⚠ Answer a scheduled run that could NOT START because the owner already had a task in flight. One task runs per owner at a time. run\_now takes the slot as soon as it frees — not 'try again now', because the slot is busy. skip drops this firing only. Unanswered, it is dropped after a week. | argument | required | meaning | | ------------- | -------- | ----------------------------------------------------- | | `action` | yes | "run\_now" or "skip" | | `note` | no | why, for the record | | `owner` | yes | the address that owns it | | `schedule` | yes | the schedule id | | `scheduledAt` | yes | the firing's time, exactly as get\_schedule prints it | ### `place_order` ⚠ Wait for a PRICE, then run a pipeline that is ALREADY SAVED. The trigger a schedule is to a clock. It holds no signature and compiles a fresh plan each time it fires, which is why one can rest for days without going stale — and why nothing is signed until the price is actually there. Use it for "buy X at Y", "sell when it reaches Y", and for unwinding a loan at a price: point it at a swap.router, loan.close or loan.shift plan. By default a short fill is ACCEPTED: it takes what the block will give, records it, and comes back for the rest. A STOP-LOSS is direction "at\_or\_below"; add `trail_bps` to make it trail the market up. A TAKE-PROFIT is the default "at\_or\_above". Point either at the entry with `protects` and it sells only what that entry actually bought. | argument | required | meaning | | ------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `amount` | yes | total size to fill, in spend's own raw units | | `chain` | yes | the chain it trades on | | `direction` | no | "at\_or\_above" (default) fills when the rate is at least the limit; "at\_or\_below" when it falls to it | | `note` | no | what it is for, for a person reading the list | | `order` | yes | an id for the order | | `owner` | yes | the OWNER address | | `partial` | no | default TRUE. False is fill-or-kill: a block that cannot give the whole size moves nothing at all | | `protects` | no | the id of the ENTRY order this one protects, which is what makes it a stop-loss or take-profit ON a position rather than a separate trade. Its size is then NOT `amount`: it is whatever the entry actually bought, less whatever the other side of the bracket already sold — so a stop and a take-profit on one entry can never sell the position twice, and neither cancels the other. `spend` must be the asset the entry receives | | `rate_amount` | yes | the price, top half: this much of spend... | | `rate_buys` | yes | ...must buy at least this much of receive. Two whole numbers in raw units, never a decimal — the floor for whatever size actually fills is worked out from them | | `receive` | yes | the asset coming IN, e.g. cbBTC | | `spend` | yes | the asset going OUT, e.g. USDC | | `step` | no | which step of that plan carries the size. USUALLY LEAVE IT OUT: empty resolves to the one step denominated in `spend`, and if the plan has none or several you are told which, by name and amount, rather than one being guessed at. Name a step only to override that. | | `task` | yes | the TaskID it runs, WITHOUT a revision | | `trail_bps` | no | makes an at\_or\_below order a TRAILING stop: it follows the best rate seen upward at this distance in basis points (500 = 5%) and never moves back down, firing on the retreat. Omit it for a stop at a fixed price. The rate you give is where the stop STARTS | ### `run_pipeline` ⚠ MAKE A SAVED PIPELINE RUN. This SPENDS REAL FUNDS. It is the ONE tool for that, and it works out WHICH of three things you meant by reading the run — you do not choose: nothing has run it STARTS the revision as authored the run stopped it RESUMES from the steps that already settled, at the same revision, and does not replay them the run completed it REPEATS — copies the plan to the next revision and runs the whole thing again. It REFUSES once first and tells you the number to pass back, because that is a second position rather than a repair something is in flight it does nothing and says what is happening So "run it", "run it again", "resume it" and "continue it" are all THIS tool with the same arguments. Do NOT save a new revision to get a stopped run moving, and do NOT author the plan under a new task id: both re-execute what has already been paid for. | argument | required | meaning | | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `owner` | yes | the OWNER address | | `repeat_as_revision` | no | ONLY to confirm running a COMPLETED plan a second time. Leave it out on the first call: the refusal says what would be executed again and names the exact number to pass here | | `revision` | no | which revision to start, or to continue onto after a correction; omit for the latest | | `task` | yes | the TaskID | ### `start_chain` ⚠ Begin a saved chain. This SPENDS REAL FUNDS: it runs the first once-stage immediately. A stage that ends stuck stops the chain and arms nothing after it. | argument | required | meaning | | -------- | -------- | ---------------------------------------------------------------- | | `chain` | yes | the id the CHAIN OF PIPELINES was saved under — not an EVM chain | ## Tools that do not spend ### `cancel_order` Stop a resting order for good. What it already filled stays filled — this stops it firing again, it does not undo anything. Refused while a run is in flight, because cancelling the row cannot recall a transaction. | argument | required | meaning | | -------- | -------- | ------------------------ | | `order` | yes | the order id | | `owner` | yes | the address that owns it | ### `check_allowance` What the OPERATING ADDRESS may draw from the owner, and whether that covers an amount. A `deposit.pull` step needs TWO things and they fail differently: the tokens have to be held by the owner, and the account has to have PERMISSION to draw them. get\_balances answers the first. This answers the second. Pass `amount` — in the asset's own base units, so 500 USDC is "500000000" — to ask whether the allowance covers a draw of that size. Without it this only reports what is currently approved, and nothing is offered to fix. WHEN IT IS SHORT the console puts an Approve button in front of the person for exactly the gap. Tell them what it is for; you cannot press it. An approval moves no money — the tokens stay in their wallet and the account gains permission to draw them — and it is the owner's signature, not this server's. validate\_pipeline already checks this for the pulls in a plan. Use this one when there is no plan yet, or when somebody asks about an allowance directly. | argument | required | meaning | | -------- | -------- | ------------------------------------------------------------------------------------- | | `amount` | no | optional: the draw to check against, in BASE UNITS (500 USDC = "500000000") | | `assets` | yes | e.g. \["USDC"] | | `chain` | no | base (default), ethereum, arbitrum | | `owner` | yes | the OWNER address that grants the allowance; the operating address is derived from it | ### `check_supported` FIRST, before anything else: check that the assets, chains and operations the person actually named are supported. Someone asks for DAI or for something on Solana and the answer is no — better known now than after a plan is built on it. | argument | required | meaning | | ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `assets` | no | every asset named, e.g. \["DAI","USDC"] | | `chains` | no | — | | `markets` | no | the lending pairs you actually mean, e.g. \[\{"operation":"collateralize","asset":"XAUt"},\{"operation":"borrow","asset":"USDC"}]. Give this whenever the request involves collateral or a loan: without it every asset is checked against every operation and combinations you did not ask about are reported, which is how a plan that works gets refused. | | `operations` | no | use these exact names — this system's word for supplying to a lending market is "collateralize", not "supply": approve, borrow, bridge, buy\_property, claim\_own\_rent, claim\_position, close\_aave\_long, close\_aave\_short, close\_aave\_single, close\_loan, collateralize, delegate\_rent, enable\_collateral, flash\_close, flash\_collect\_levered, flash\_decrease, flash\_increase, flash\_increase\_from\_aave, flash\_increase\_lev, flash\_mint\_levered, flash\_move\_from\_aave, flash\_move\_to\_aave, flash\_rebalance, flash\_reposition, flash\_split, harvest\_delegated, presign\_order, pull\_from\_owner, receive, redeem\_rent, repay, revert\_borrow, revert\_create\_borrow, revert\_mint\_create\_borrow, revert\_remove, revert\_repay, revert\_repay\_withdraw, sell\_property, send, shift\_loan, swap, uni\_close\_at\_tick, uni\_collect, uni\_decrease, uni\_increase, uni\_mint, uni\_mint\_single, uni\_rebalance, uni\_reposition, uni\_split, uni\_withdraw, withdraw | ### `find_skill` ASK YOUR QUESTION HERE FIRST. Returns the ANSWER — the handful of sections that address it, from across every guide, each cited by file and line. Not a list of names to go and read: the text you need comes back in this one call. Ask in the words a person used — "only fill if the price is right", "unwind a loan without selling first" — and it searches the prose AND the exact identifiers. Prefer this to read\_skill, which returns whole documents and costs several times as much for the same answer. Call with no query to see the whole shape of what exists. | argument | required | meaning | | -------- | -------- | ------------------------------------------------------------------------------------- | | `query` | no | the question, in ordinary words — what you are trying to do, or what you need to know | ### `forget_run` GIVE UP a run that stopped part-way, so this owner can start something else. It spends nothing and it is not an undo. DO NOT CALL THIS ON YOUR OWN INITIATIVE. It is the one destructive verb you hold: it throws away a record of somebody's money that cannot be put back, and no refusal you are reading is permission to use it. Call it ONLY when the person has said, in their own words and in this conversation, to give that run up — abandon it, drop it, forget it, get rid of it. `said` carries those words and the call is refused without them. If they have not said it, ASK; a refusal you cannot get past is a thing to report, not a thing to clear. NEVER AFTER stop\_run, in the same breath. Stopping and giving up are two different decisions and the person has made only the first: a run that has just been stopped is one they may still want to carry on. Calling this because stop\_run appeared to change nothing is the exact mistake it exists to prevent — stop is SUPPOSED to leave the slot held. THIS IS NOT STOP. stop\_run ends a run and deliberately leaves it holding the owner's slot — that is what makes stop-then-run-again a pause. A run that stopped part-way holding settled steps BLOCKS every other start for that owner, on purpose, so a second position is never opened against a wallet the first is still holding. This removes the run record, which is the thing doing the blocking. Use it when a stranded run is refusing a start and that run is genuinely finished with. If it should be carried on instead, say run it again and run\_pipeline continues it — do not forget it first. NOTHING ON CHAIN IS UNDONE, and the settled steps stay settled: they are keyed on the task and revision, not on the record this removes, so running the task again still continues from them rather than replaying them. | argument | required | meaning | | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `owner` | yes | the OWNER address | | `reason` | no | why, in the person's own words, for whoever reads the record | | `said` | yes | WHAT THE PERSON SAID, quoted from this conversation, asking for this run to be given up. Required, and it must be their sentence and not your summary of one: this is the only evidence that the decision was theirs. If you cannot quote it, they have not made it | | `task` | yes | the TaskID whose run record should be removed. Required: an owner may have several, and forgetting the wrong one cannot be undone | ### `get_account_state` Show the owner and the operating address — the account the agent operates and every plan spends from — and what each currently holds. Call this before deciding any amount. | argument | required | meaning | | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `owner` | no | the OWNER address. Omit it — the conversation already says whose account this is, and it will be filled in. Pass `account` instead if you have only the operating address. | ### `get_balances` Read several asset balances for several holders at once. Pass "chain" to read somewhere other than base. Holders are roles: owner\_account (the OPERATING ADDRESS, which is what every plan spends from), owner\_wallet (the OWNER), or a plain 0x address. Pass the owner — the operating address is derived from it. | argument | required | meaning | | --------- | -------- | ---------------------------------------------------------------------------------- | | `assets` | no | e.g. \["USDC","cbBTC"] | | `chain` | no | base (default), ethereum, arbitrum | | `holders` | no | e.g. \["owner\_account"] | | `owner` | yes | the OWNER address these balances are for; the operating address is derived from it | ### `get_bridge_cost` What to SEND so that a wanted amount lands after a crossing, or what a given amount will deliver. Call it whenever a plan bridges. DO NOT WORK THIS OUT IN PROSE. A crossing keeps a fee, so sending exactly what the far side spends lands short and the run stops AFTER the money has already crossed — and the near miss is the common one: a gross-up rounded to the nearest cent is short by a fraction, which reads as correct and is not. Every "short 0.1 USDC" refusal is this arithmetic done by hand. Give must\_arrive to size a crossing, which is the usual direction: it returns the exact integer for the bridge step's Amount. Give sending to check an amount already written. Raw units both ways. | argument | required | meaning | | ------------- | -------- | --------------------------------------------------------------------------------------------------------------- | | `asset` | no | USDC by default, and today the only asset any bridge here carries | | `from` | yes | the chain the money leaves | | `must_arrive` | no | raw units that have to LAND, if you are sizing the crossing. USDC has 6 decimals, so "250000000" is 250 dollars | | `sending` | no | raw units being SENT, if you are checking an amount already written | | `to` | yes | the chain it lands on | ### `get_chain` Read a CHAIN: an ordered arrangement of pipelines, which runs once and which recurs, plus where a running one has got to. A strategy is rarely one plan — a setup that runs once and a loop that runs monthly are edited and approved on different rhythms. Call this before changing one. | argument | required | meaning | | -------- | -------- | ---------------------------------------------------------------- | | `chain` | yes | the id the CHAIN OF PIPELINES was saved under — not an EVM chain | ### `get_fill_at_price` AT THIS PRICE, HOW MUCH FILLS RIGHT NOW. The question a limit order is made of, and the one the ladder cannot answer: get\_tradeable\_size tells you what a COST buys, this tells you what a PRICE buys. Call it before place\_order whenever somebody names a price. An order for $1m at a rate that clears $40k is not wrong, but the person should know it before it rests for a week — and if nothing fills, that is a real answer rather than an error: the price asked for is better than the market. Measured across every pool, which is what a plan here executes. The price is a PAIR of raw amounts, never a decimal. | argument | required | meaning | | ------------- | -------- | -------------------------------------------------------------------------- | | `amount_in` | yes | the whole size you want filled, in raw units of asset\_in | | `asset_in` | yes | what is being spent, e.g. USDC | | `asset_out` | yes | what is being bought, e.g. WETH | | `chain` | no | base (default), ethereum, arbitrum | | `rate_amount` | yes | the price, top half: this much asset\_in… | | `rate_buys` | yes | …must buy at least this much asset\_out. The same pair place\_order takes. | ### `get_lending_rates` WHAT EVERY MARKET CHARGES RIGHT NOW: supply APY, borrow APY, how much of it is already borrowed, and the loan-to-value at which it liquidates. Aave v3's reserves are enumerated FROM THE POOL, so it covers every asset Aave lists and not only the ones this system has a name for; Aave v4's from its hub; Morpho's are the curated markets. Call it before choosing a venue to borrow from, before quoting anybody a rate, and before assuming two venues cost the same — they routinely differ by more than a point on the same asset on the same chain. ASK ONCE, FOR EVERYTHING THE PLAN TOUCHES. `chains` and `assets` are lists: a plan lending XAUt on ethereum and cbBTC on base is ONE call, \{"chains":\["ethereum","base"],"assets":\["XAUt","cbBTC"]}. Narrowing to one pair at a time is a round trip per pair and was measured costing three calls for one plan. Omitting both is also fine and returns every market on every chain. | argument | required | meaning | | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `asset` | no | one symbol. Prefer `assets` | | `assets` | no | the symbols the plan lends or borrows, e.g. \["XAUt","cbBTC"]. Matches either side of a market, so cbBTC finds the market it collateralises as well as the one it borrows. Omit for every market | | `chain` | no | one chain. Prefer `chains` | | `chains` | no | ethereum, base, arbitrum — as many as the plan touches. Omit for all three | | `venue` | no | aave\_v3 \| aave\_v4 \| morpho \| revert\_vault; omit for all of them | ### `get_lp_yield` BEFORE providing liquidity: what a range would have COLLECTED, from each pool's real daily history, on every chain and fee tier at once. Answers the three questions a spot APY cannot — which network, which fee tier, and which range. An advertised APY is the last 24 hours across a pool's whole book. This walks history a day at a time: the pool's fees that day, times your liquidity over the pool's, and ZERO on days the price left your band. A band that looked excellent was in range 19% of one window and idle for the rest, which no APY anywhere says. PASS EVERY RANGE YOU ARE WEIGHING IN ONE CALL. `ranges` is a list and each costs nothing extra, against a round trip per range otherwise. Omit it to get the widest band that held the price, which is the ceiling a narrower one is measured against. A range is "so many QUOTE per one BASE". With one stablecoin that is dollars per coin and needs no thought; on WBTC/WETH or USDC/USDT set `priced_in`, because 25-40 and 0.025-0.04 are the same band from opposite ends. The direction used is always reported. IT ALSO ANSWERS WHAT YOU END UP WITH. Every answer carries a CASH IN HAND block: what the deposit is worth at the end, the impermanent loss, and the total against simply holding. Report that, not the fee figure alone — fees are half a ledger and people read them as the outcome. Still not modelled: compounding, rebalancing and gas. For "what if the price keeps going" pass `exit_prices`; for "what if I enter at X and leave at Y" pass `entry_price` and `exit_price`. A band traversed end to end sells every coin at the GEOMETRIC MEAN of its bounds, not at the price the asset finished at, and then stops earning — which is why a fast run to the top of a band is a bad outcome and not a good one. Fees are NET of Uniswap's protocol fee, which the UNIfication vote switched on during 2026 — a quarter of the swap fee on the 0.01% and 0.05% tiers, a sixth on 0.3%. The subgraph's own feesUSD is gross, so these figures are deliberately lower than a reader's own arithmetic against it. REPORTING THE ANSWER, because this has been got wrong: the window DEFAULTS TO TWO YEARS, so name the window you actually got — the answer states its own length in days and years on the first line. The table gives two different rates: `total` is the return over the WHOLE window and `per year` is that annualised. Quoting `total` as an annual rate doubles it on a two-year window, which is exactly what happened to a 48.9% two-year figure reported as 48.9% a year. `per year` is an APR and NOT an APY: v3 keeps a position's fees in a separate balance, so nothing compounds unless the owner collects and re-adds it by hand. | argument | required | meaning | | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `capital` | no | position size in US DOLLARS, whatever the pair is priced in — both legs are valued in dollars via the quote token's own USD price. Defaults to 10000. It changes the ANSWER and not just its scale — fees split by liquidity, so a position large relative to its pool earns a share it could not earn twice, and the tool flags that | | `chains` | no | ethereum, base, arbitrum. Omit for all three | | `entry_price` | no | a HYPOTHETICAL entry, for "what if I get in at X and out at Y". Must be given with exit\_price. The position half is then exact arithmetic; fees are reported as a rate per year against a holding period, because an entry and an exit do not determine them | | `exit_price` | no | the other end of that traverse. Goes with entry\_price | | `exit_prices` | no | other prices to value the SAME position at, e.g. \[45000, 120000, 150000]. Shows the shape of the bet: the position value is exact at each, and stops moving entirely past the band's ends. Use it whenever someone asks what happens if the price keeps going | | `fee_tiers` | no | in hundredths of a bip: 500 is 0.05%. Omit for every tier | | `from` | no | window start, YYYY-MM-DD. Defaults to two years back | | `priced_in` | no | the symbol a range is written IN — "so many of this per one of the other". Needed only when neither token is a stablecoin (WBTC/WETH) or both are (USDC/USDT), where 25-40 and 0.025-0.04 are the same band from opposite ends. Defaults to the stablecoin, else the pool's own quote token; the choice is always reported | | `ranges` | no | bands as "low-high" in dollars per coin, e.g. \["58000-120000", "84000-120000"]. Omit for the widest band that held the price | | `to` | no | window end, YYYY-MM-DD | | `tokens` | yes | exactly two symbols, one a stablecoin: \["cbBTC", "USDC"] | ### `get_orders` What is resting, what filled, and in how many bites. A partially filled order is working, not failing — it took what the price would give and is waiting for the rest. | argument | required | meaning | | -------- | -------- | ---------------------------------------------------------------- | | `owner` | no | the OWNER address; omit it and this conversation's owner is used | ### `get_pipeline` Read back a pipeline that was saved, with its revision history AND whether a run of it has started, is in flight, or has STOPPED. Call this BEFORE changing a plan you did not just write, and before running one again: a revision cannot be edited in place, so a change means resending the whole document at the next revision, and reconstructing it from memory is how steps go missing. | argument | required | meaning | | -------- | -------- | ----------------------------- | | `task` | yes | the TaskID it was saved under | ### `get_positions` WHAT THIS OWNER ALREADY OWES AND HAS SUPPLIED, read from each venue rather than from any record this system keeps. Covers Aave v3, Aave v4 and Morpho, on every chain, for BOTH the operating address and the owner's own wallet — they are separate borrowers and a debt on either is a real debt. Call this before any borrow, any repay, any loan shift, and before saying anything about what somebody holds. A position is the only thing that says whether a borrow can succeed: get\_lending\_rates says what it would cost, which is a different question. | argument | required | meaning | | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `chain` | no | ethereum, base or arbitrum. OMIT FOR ALL THREE, which is almost always what you want — a position on a chain you did not name is invisible, not absent | | `owner` | yes | the OWNER address; the operating address is derived from it | | `venue` | no | aave\_v3 \| aave\_v4 \| morpho; omit for all of them | ### `get_prices` USD prices, from whichever source can answer for the asset. A tradeable asset (USDC, cbBTC, WETH) is quoted through the POOLS a swap would route through — the price you would actually get. A property token has no market and is quoted from 0xequity's oracle, which is the price its OCLR router transacts at. This prices ONE UNIT; for a size that matters use get\_swap\_cost, which prices that size. PASS EVERY ASSET YOU CARE ABOUT IN ONE CALL. `assets` is a list and the cost of adding to it is one quote each, against a round trip per call otherwise — a plan touching four assets asked four times and spent four turns learning what one would have told it. Each asset is priced on EVERY chain that carries it, one row per chain, because the same token is not the same price in two places: WETH quoted $2429 on ethereum and $2492 on base within a second of each other. An asset absent from some chains is still priced on the ones that have it, and the others are named under it — so XAUt answers with its ethereum price rather than with the fact that Base does not carry it. | argument | required | meaning | | -------- | -------- | ------- | | `assets` | no | — | ### `get_run_status` Report how a submitted pipeline is going, step by step. | argument | required | meaning | | ---------- | -------- | ------- | | `owner` | yes | — | | `revision` | no | — | | `run` | no | — | | `task` | yes | — | ### `get_schedule` Read a SCHEDULE — the recurring trigger attached to one pipeline — with its next dates and what became of past firings. A firing marked BLOCKED is waiting for a person and will be dropped if nobody answers. | argument | required | meaning | | ---------- | -------- | --------------- | | `schedule` | yes | the schedule id | ### `get_swap_cost` What a specific trade will actually cost, all in — and what a BOUND would do to it before you write one into a plan. JUDGE A TRADE ON cost\_vs\_best\_spot\_pips, never on price\_impact\_pips: impact is measured against the route this quote chose and excludes the pool fee, so at size it can FALL while the trade gets more expensive. If cost\_vs\_best\_spot\_pips comes back null that means UNMEASURED, not free — read read\_this, which says what to do instead. Call this before committing to an amount a person will care about. Send max\_impact\_bps or cost\_bps to ask what that bound leaves: both shrink the offer, and offered\_amount\_in beside amount\_in is the answer. Neither is slippage — slippage never changes the trade, only the floor it must clear. | argument | required | meaning | | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `amount_in` | yes | raw units of asset\_in — USDC has 6 decimals, so "1000000" is one dollar | | `asset_in` | yes | — | | `asset_out` | yes | — | | `chain` | no | base (default), ethereum, arbitrum | | `cost_bps` | no | OPTIONAL. Trade at most what the BOOK takes at this marginal cost, in basis points. A different question from max\_impact\_bps: this one asks how large a trade the book carries, that one caps what a chosen size does. Both may be sent; the smaller wins and bound\_by says which. | | `max_impact_bps` | no | OPTIONAL. Cap what this trade does to the pool, in basis points. The service shrinks the OFFER until the impact it reports fits, so compare offered\_amount\_in with amount\_in to see what the cap would cost you in size. | | `max_slippage` | no | basis points; defaults to 100 | ### `get_tick_range` Turn a PRICE RANGE into the tick\_lower and tick\_upper a Uniswap V3 mint takes. Call it for every uni.\* or flash.\* step that carries ticks. DO NOT WORK TICKS OUT IN PROSE. Between a price and a tick sit a logarithm, a DECIMALS adjustment, the pool's tick spacing and Uniswap's own token ordering — which is by address, so it cannot be guessed from the symbols. Only the spacing reverts when it is wrong. Forget the decimals term on WETH/USDC and the tick is out by about 276,310: a valid int24 that mints happily, at prices nobody asked for, holding one token and earning nothing. It reports the prices the rounded ticks actually mean, which are never exactly the ones asked for. Say those back to the person. | argument | required | meaning | | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `chain` | no | base (default), ethereum, arbitrum | | `fee` | yes | the pool's fee TIER in its own units: "100", "500", "3000" or "10000". Each has a tick spacing fixed with it | | `range` | yes | a price band as "2000-4000", OR A SINGLE PRICE as "2500" — one price returns ONE tick, rounded to the nearest multiple of the pool's spacing, which is the shape uni.split's `tick` takes. The band form returns the pair a mint takes. Either form is read as token\_b per one token\_a; if the pool's own order is the other way round the answer says so and uses the reciprocal | | `token_a` | yes | one side of the pair, by SYMBOL | | `token_b` | yes | the other side, by SYMBOL | ### `get_tradeable_size` THE INVERTED QUESTION, and the one an order is actually made of: not "what does this size cost" but "what size costs at most N basis points". Returns a size per cost level, in one call. Use it before choosing any large amount, and before offering to split an order into tranches — whether splitting helps depends on the pair and this is what decides it. Read `saturated` (the size is a floor, not a maximum) and `pools_answered` (levels measured over different pool counts are not on the same curve) before believing a number. | argument | required | meaning | | ----------- | -------- | ------------------------------------------------------ | | `asset_in` | yes | what is being spent, e.g. USDC | | `asset_out` | yes | what is being bought, e.g. cbBTC | | `chain` | no | base (default), ethereum, arbitrum | | `cost_bps` | no | cost levels in basis points; defaults to \[5,10,25,50] | ### `get_uni_positions` THE UNISWAP POSITIONS THIS OWNER ALREADY HOLDS — token id, pair, fee tier, price band and uncollected fees, read from the position manager on each chain. get\_positions is LENDING and does not cover these. Call this before writing any plan that acts on a position the person already has: uni.decrease, uni.collect and every revert.\* step take a `position_id`, and it is a token id that cannot be guessed or derived. Asking the person for it is the wrong move when this answers it. Reads the operating address AND the owner. A position pledged as collateral is NOT listed — the Revert vault holds the NFT while the loan is open, so the position manager reports it as the vault's. | argument | required | meaning | | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `chain` | no | ethereum, base or arbitrum. OMIT FOR ALL THREE, which is almost always what you want — a position on a chain you did not name is invisible, not absent | | `owner` | yes | the OWNER address; the operating address is derived from it | ### `list_capabilities` The operations a pipeline step can use, with the exact ref to copy, the parameters, and what Amount means for each. Call this FIRST, before writing any plan. PASS THE REQUEST AS THE QUERY — in the person's own words, the whole thing, not one operation at a time: "take $1000 from my account and swap $200 to cbBTC and \$200 to WETH" returns the funding step and the swap step in full and names the rest. Leave the query off only when you genuinely need the whole catalogue; it is several times larger and the operations you need are harder to find in it. | argument | required | meaning | | -------- | -------- | --------------------------------------------------------------------------------------- | | `query` | no | what the person asked for, in their words — or an operation id, to get that one in full | ### `list_networks_and_assets` The chains, the assets each supports, and their decimals. Check here before naming an asset or a chain. ### `read_skill` Read WHOLE guides, up to 3 — thousands of words each. Reach for it only when find\_skill has shown you the right document and you need the rest of it: a procedure with steps that depend on each other, or a subject you are going to work in for several turns. For a QUESTION, find\_skill answers it directly and for a fraction of the cost. The answer names which skills go with the ones you read. | argument | required | meaning | | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | no | one skill name, or several separated by commas — up to 3. Use find\_skill if you do not know the name. The answer says which skills go with the ones you read. | ### `save_chain` Arrange pipelines that are ALREADY SAVED into an ordered chain. Starts nothing. A stage with no scheduleId runs its pipeline once and the chain waits for it to SUCCEED; a stage with one arms that schedule and carries on. Save the pipelines and any schedules first — a stage naming a pipeline that is not stored would fire into nothing. | argument | required | meaning | | -------- | -------- | --------------------------------------------------------------------- | | `chain` | yes | an id for the chain | | `name` | yes | how a person will recognise it | | `owner` | yes | the OWNER address | | `stages` | yes | in order. Each names a taskId, and a scheduleId to make it recurring. | ### `save_pipeline` Store a validated pipeline WITHOUT running it. Validates first and refuses to store anything that would not run. Call this once the plan is agreed and validated: it gives the console something to link to, so the person can open the pipeline instead of reading it pasted into the conversation. | argument | required | meaning | | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `amounts` | yes | REQUIRED. What each step moves, in the ASSET'S OWN UNITS — one row per step that has a written Amount. This is compared against the raw integers in `plan`, and a disagreement of ten times or more is refused. It is a MAGNITUDE check, so ordinary headroom, a fee or a rounded figure all pass: write what the person said and do not tune it to the document. (1) Write it as the person said it: "250.00", not the raw integer. (2) Take the figure from the REQUEST, not by dividing your own Amounts back out — the point is to catch a conversion that went wrong. (3) For a property.buy step state what it SPENDS (params.max\_spend, in params.currency), never the share count. (4) Steps whose amount is an earlier step's output need NO row and must not be given an invented one, and neither do rent.redeem and rent.claim\_position, whose Amount is a token id rather than money. A refusal names every step it wants a row for, so nothing has to be guessed. | | `plan` | yes | The whole pipeline document: \{"TaskID":"...","Owner":"0x...","Revision":1,"Steps":\[...]} | ### `save_schedule` Attach a recurring trigger to a pipeline that is ALREADY SAVED. It does NOT arm it and does NOT run anything. A schedule is deliberately not part of the plan document: a step's id goes on chain and its bytes are in the hash somebody approved, and a cron has neither property — kept in the plan, changing the frequency would be refused as rewriting history. | argument | required | meaning | | ---------- | -------- | ------------------------------------------------------------ | | `note` | no | what it is for, for a person reading the list | | `owner` | yes | the OWNER address | | `schedule` | yes | an id for the schedule | | `spec` | yes | cron, e.g. "0 9 1 \* \*" for 09:00 on the 1st, or "@monthly" | | `task` | yes | the TaskID it runs, WITHOUT a revision | | `timezone` | no | IANA name; UTC if omitted | ### `stop_run` STOP, PAUSE or TERMINATE a run of a task — all three are this one tool, because there is one act underneath. It spends nothing. It is NOT an undo. Everything already on chain stays exactly where it is; this ends the run that was managing it. Say that when you report it. PAUSING IS STOP THEN RUN AGAIN. Nothing is replayed: run\_pipeline picks the task back up from the steps that had already settled. Use this the moment somebody says stop — do not send them to the console for it. | argument | required | meaning | | -------- | -------- | ----------------------------------------------------------------------------------------------------------------- | | `owner` | yes | the OWNER address | | `reason` | no | why, in the person's own words, for whoever reads the record | | `task` | yes | the TaskID whose run should end. Required: an owner may have several, and stopping the wrong one cannot be undone | ### `validate_pipeline` Check a pipeline against the real compiler WITHOUT running it. Returns VALID, or REJECTED with the reason. Always validate before submitting, and validate again after every fix. | argument | required | meaning | | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `amounts` | yes | REQUIRED. What each step moves, in the ASSET'S OWN UNITS — one row per step that has a written Amount. This is compared against the raw integers in `plan`, and a disagreement of ten times or more is refused. It is a MAGNITUDE check, so ordinary headroom, a fee or a rounded figure all pass: write what the person said and do not tune it to the document. (1) Write it as the person said it: "250.00", not the raw integer. (2) Take the figure from the REQUEST, not by dividing your own Amounts back out — the point is to catch a conversion that went wrong. (3) For a property.buy step state what it SPENDS (params.max\_spend, in params.currency), never the share count. (4) Steps whose amount is an earlier step's output need NO row and must not be given an invented one, and neither do rent.redeem and rent.claim\_position, whose Amount is a token id rather than money. A refusal names every step it wants a row for, so nothing has to be guessed. | | `plan` | yes | The whole pipeline document: \{"TaskID":"...","Owner":"0x...","Revision":1,"Steps":\[...]} | ### `watch_run` Wait for a running pipeline to make progress, then report it. Blocks until a step changes state or the run finishes, so every answer has news in it. Call it repeatedly after submitting, and tell the person what each one says. | argument | required | meaning | | -------------- | -------- | ---------------------------------------------- | | `owner` | yes | — | | `revision` | no | — | | `run` | no | — | | `task` | yes | — | | `wait_seconds` | no | how long to wait for news; default 45, max 120 | ## Related topics - [The tool server](/tools.md) - [Skills](/skills.md) - [FAQ](/faq.md) - [Non-custodial, and unilateral control](/kernel.md) - [How it works](/platform.md)