# Fin documentation > REST API documentation for integrating an agent backend. MCP endpoint: /mcp (Streamable HTTP; tools: search_docs and get_doc). Full documentation: /llms-full.txt OpenAPI: /openapi.json - [Introduction](/index.md): Give each of your users an AI agent, through one API. - [Quickstart](/quickstart.md): Create a user, sign them in and get the agent's first reply. - [How Fin works](/concepts.md): Users, conversations, runs, approvals, money and automations, and how they fit. - [Base URL](/base-url.md): Use the API origin your deployment operator gives you, and append each operation's path to it: - [Authentication](/authentication.md): Every request carries your API key. Requests about a user also carry that user's session token: - [Pagination](/pagination.md): Lists take `limit` and `cursor` and answer `{ data, nextCursor }`, plus `total` where the operation says so. Pass `nextCursor` back as `cursor` to get the next page; `null` means you have reached the end for now. Keep the other query parameters the same while paging. - [Idempotency](/idempotency.md): Commands that create something take an `Idempotency-Key` header: a UUID you generate and keep for that request. If a response is lost, send the same request again with the same key and the same body; you get the original result back and nothing happens twice. The same key with a different body is refused with `409 request_key_conflict`. - [Rate limits](/rate-limits.md): All your API keys share one set of limits: by default 600 requests a minute, 32 runs in progress and 32 open event streams (4 per user), plus daily and monthly AI spend. Read yours with [Get your rate limits](/api-reference/partner/quotas). - [Versioning](/versioning.md): This is version 7 of the API, served under `/v1`. Responses can gain new fields at any time, so ignore fields you don't recognise. Request bodies are strict: an unknown field is refused. Enums are closed: a value that isn't documented is a bug to report, and a new value only ships with a new API version. - [Errors](/errors.md): Every failure is an RFC 9457 problem (`application/problem+json`). `type` names the kind, `reason` is the machine-readable why, `retryable` says whether repeating the same request can succeed, and `requestId` is what to quote. A resource that belongs to someone else answers exactly like a missing one. - [Events](/events.md): The journal and the stream carry one shape. On the stream, `id` is the journal `seq`, `event` is the type below, and `data` is a `{ delivery, seq, payload }` frame; resume with `Last-Event-ID` or `?cursor=`. - [Streaming & events](/streaming.md): Show the agent's work live and reconnect without missing anything. - [Deposits, withdrawals and trades](/wallet-transfers.md): Create the agent wallet, fund it, swap and withdraw from it, and follow trades. - [Idea baskets](/idea-baskets.md): Read enabled partners' idea baskets, settlement quantities and estimated values. - [Solana tokens](/solana-tokens.md): Find, rank and judge Solana tokens by their mint, and read the agent's Solana account. - [Automations](/automations.md): List, pause, resume, run and delete automations, and send them events. - [Notifications](/notifications.md): Show what Fin told each user in an inbox, and ping their devices from your server. - [Suggestions](/suggestions.md): The moves Fin suggests on the user's whole account, read per page. - [Market briefs](/market-briefs.md): What part of the market did and why, with sources, for your partner key alone. - [Market news](/market-news.md): The market's stories, headlines, moves and money flows, for a news page. - [Usage and limits](/usage-and-quotas.md): Your AI usage, your rate limits, and what happens when you reach them. - [Building with the packages](/packages.md): A typed client for your server and Fin's blocks for your React chat. - [Packages quick reference](/packages-quick-reference.md): The calls you use most from both packages, on one page. - [SDK quickstart](/sdk-quickstart.md): Create a user, sign them in and stream the agent's reply from your server. - [SDK recipes](/sdk-recipes.md): Relay a conversation, approve money actions, fund and withdraw, handle errors. - [SDK reference](/sdk-reference.md): Every method, option, error and type @nearai/financial-agents-sdk exports. - [React quickstart](/react-quickstart.md): Draw a Fin conversation in your own React chat with Fin's blocks. - [Components reference](/react-components.md): Every block @nearai/financial-agents-react exports: what it draws, its props and its parts. - [Theming](/react-theming.md): Make Fin's blocks look like your product, or draw them with your own markup. - [View models](/react-model.md): The logic behind Fin's blocks, for your own markup and your server. - [Tokens and chains](/tokens-and-chains.md): Token icons, network badges and your own token list. - [Docs for AI agents](/agents.md): Connect your coding assistant to the same documentation you read. - [Open a perps account](/api-reference/perps/open-account.md): Opens the user's Hyperliquid perpetuals account. Use it after creating the agent wallet and enabling perps for the user to have the account ready before any trade; no additional signature is needed because opening moves no funds. The agent's first deposit or opening order in chat opens it too, so calling this is optional. Returns the same account on every repeat, with a live balance observation when available. Send an `Idempotency-Key` for retries, then use Get a perps account to refresh its state. - [Get a perps account](/api-reference/perps/get-account.md): Returns the user's Hyperliquid perpetuals account, its current balance observation and each open position. Use it to refresh an account opened with Open a perps account or by the agent's first deposit or opening order; before opening it, the response is not found. An unavailable state means the balance could not be read, not that the account disappeared. The positions' unrealized PnL is already in the account value, so never add the positions to it. - [Open a prediction-market account](/api-reference/prediction/open-account.md): Opens the user's Polymarket account: a Deposit Wallet on Polygon that holds the agent's pUSD and positions, controlled by a key Fin holds. Use it once, after creating the agent wallet and enabling prediction-market trading for the user, to have the account ready before any trade; no additional signature is needed because opening moves no funds. The agent's first funding or order opens it too, so calling this is optional; that first attempt is refused while the account finishes opening. The first call answers with the account, its `status` `opening`; Fin then has Polymarket's relayer create the wallet and set its trading approvals without another call, so poll Get a prediction-market account until `status` is `ready`. A repeat with the same `Idempotency-Key` returns the same account. - [Get a prediction-market account](/api-reference/prediction/get-account.md): Returns the user's Polymarket account, whether it is still opening or ready, its live pUSD balance and the positions it holds. Use it to follow an account opened with Open a prediction-market account or by the agent's first funding or order; before opening it, the response is not found. An opening account becomes ready on its own, so poll this route rather than opening again. An unavailable balance or positions read means Polygon or Polymarket could not be read, not that the wallet is empty. - [Prepare a Polymarket order](/api-reference/prediction/prepare-order.md): Step 1 of placing a Polymarket order the user makes themselves. Checks the order against the user's prediction-market account and returns it as the exact `order` to show and sign, with `authorization.message` for the user to sign and the `requestKey` to send as the `Idempotency-Key`. Use it for an order the user places from your own screen; the agent proposes its own orders in chat. Nothing is reserved or placed. Call Place a Polymarket order before `authorization.expiresAt`. - [Place a Polymarket order](/api-reference/prediction/place-order.md): Step 2 of placing a Polymarket order the user makes themselves. Places the prepared order from the user's prediction-market account, after the custody worker checks it against the live market and its signed fee and spend caps. Send the prepared `order`, the user's signature of its `authorization.message`, and its `requestKey` as the `Idempotency-Key` header. Returns the order and its latest fills, as Get a prediction order does; an `uncertain` order may already exist at Polymarket, so keep reading it rather than placing a replacement. If this call times out, send it again unchanged: you get the same order back, never a second one. - [List prediction orders](/api-reference/prediction/list-orders.md): Lists your prediction orders and their latest fills. Follow nextCursor to read more. A match may still be awaiting settlement; open an order to follow it or request cancellation. Existing orders remain readable when trading is disabled. - [Get a prediction order](/api-reference/prediction/get-order.md): Returns your prediction order and its latest fills. An uncertain submission may already exist at Polymarket: keep reading this order rather than placing a replacement. Cancellation stops only future matches. - [Cancel a prediction order](/api-reference/prediction/cancel-order.md): Requests cancellation of your prediction order without another approval. Available even when trading is disabled. Fills can race cancellation and remain visible; read this order until cancellation and any matched trades settle. - [Prepare a Solana trade](/api-reference/solana/prepare-trade.md): Step 1 of a Solana buy or sale the user makes themselves from a token's page, with no agent run. Checks the trade as the agent's own buys and sales are checked (a buy needs the `solana` feature, a sale the opened Solana account, and the token must be one Fin trades) and returns it as the exact `trade` to show and sign, with `authorization.message` for the user to sign and the `requestKey` to send as the `Idempotency-Key`. Nothing is reserved or moved. A USDC buy from an Agent API wallet first funds the Solana account, which its agent pays only once the user allowed it: until then this refuses `destination_not_allowed`, and Add a withdrawal destination with venue `solana` allows it with one signature (naming the account opens it, which moves nothing). Call Place a Solana trade before `authorization.expiresAt`. - [Place a Solana trade](/api-reference/solana/place-trade.md): Step 2 of a Solana buy or sale the user makes themselves. Starts the prepared trade from the agent's own Solana account: a USDC buy first moves its USDC to that account as SOL through 1Click, then swaps on Jupiter; a sale swaps, then sends its proceeds back to the agent wallet unless they stay as SOL. Send the prepared `trade`, the user's signature of its `authorization.message`, and its `requestKey` as the `Idempotency-Key` header. Returns the trade, its `status` `processing` while it runs, for up to nine minutes past the signature; follow it with Get a Solana trade until its status is final. One trade runs at a time per user. If this call times out, send it again unchanged: you get the same trade back, never a second one. - [Get a Solana trade](/api-reference/solana/get-trade.md): Returns a Solana trade the user placed themselves: its status and why it failed, the step it is on while it runs, what it paid and received, and every transaction it signed. A trade's status is final by its `completeBy`; poll this route until then rather than placing it again. Trades placed here are not in the activity feed, which lists what the agent did. - [Open a Solana account](/api-reference/solana/open-account.md): Opens the agent's own Solana account: a Solana address controlled by a key Fin holds, separate from the agent wallet's. Use it after creating the agent wallet and enabling Solana trading for the user; no additional signature is needed because opening moves no funds. Returns the same account on every repeat, with a live read of its SOL and recognized token balances. Send an `Idempotency-Key` for retries, then use Get a Solana account to refresh it. - [Get a Solana account](/api-reference/solana/get-account.md): Returns the agent's Solana account, its SOL reserve and recognized token balances with exact amounts and available prices. Use it to refresh an account already opened with Open a Solana account; before opening it, the response is not found (`no_account`). Recognized tokens are canonical wrapped SOL, venue-verified tokens without a suspicious flag whose mint facts match the chain, or tokens this account has a confirmed landed buy of. A recognized token without a price remains listed and counted in `unpricedCount`; unrecognized tokens contribute to neither the list nor its totals. A `holdings` status of `unavailable` means balances or recognition evidence could not be read, never an empty account. - [Search Solana tokens](/api-reference/solana/search-tokens.md): Finds Solana tokens by ticker, name or a pasted mint address, best match first, each with Fin's risk verdict. Use it to turn what a person says into a mint. A ticker is not unique on Solana: when `ambiguous` is true several candidates share the top symbol, so show them and let the person choose by mint, never pick by symbol alone. A pasted mint answers that token alone. Needs the Solana feature to be on for the user. - [List Solana tokens](/api-reference/solana/list-tokens.md): Lists sampled Solana candidates by activity ranking, token membership and optional liquidity, capitalization, age or launchpad filters. Use the default meme membership for positively identified memecoins, or the new lane for recent launches whose category may be unconfirmed. Returns the ranking reason, evidence gaps, source coverage and a nextCursor; pass that cursor with the same filters for the next page of the fixed snapshot. Young or thin tokens remain visible with warnings unless your filters exclude them. Needs the Solana feature to be on for the user. - [List token sparklines](/api-reference/solana/list-token-sparklines.md): Returns a small price line for each token named, over the last hour, 6 hours or 24 hours: at most 32 prices, oldest first, from what Fin itself sampled from the data source. Use it to draw a line beside each row of a token list, in one read for the page; use Get a token chart for one token's full chart. A token with no line says why: `not_sampled` when Fin read no price for it in the window, `too_sparse` when what it read would mislead. Leave the line out then, rather than draw what there is. Needs the Solana feature to be on for the user. - [List token launch status](/api-reference/solana/list-token-launch-status.md): Says where each token named stands on its launchpad: `curve` with how far along a bonding curve it is, `graduated` with when it left for an open pool, or `unknown`. Use it to show launch progress beside a list of tokens, in one read for the page; Get a Solana token's `bondingProgressPct` states the same progress for one token. Only pump.fun's curve can be read, so a token on another launchpad's curve is `unknown`, as is any token while the chain or the data source cannot be read: its `launchpad` and `graduated` on a token read still say where it launched. Needs the Solana feature to be on for the user. - [Get a Solana token](/api-reference/solana/get-token.md): Returns one Solana token by mint with market activity, classification, evidence sufficiency and the mint's risk verdict. Use it to research a discovered token or check one before a trade; resolve an ambiguous name with Search Solana tokens first. Returns missing evidence explicitly, and tradable reports current buy eligibility rather than a recommendation. Read Get a token chart for history appropriate to the token's age. Needs no feature flag, so existing holdings remain readable while buying is off; an address that is not a token is not found. - [Get a token chart](/api-reference/solana/get-token-chart.md): Returns up to 200 recent closing prices from a token's deepest pool, oldest first, with their actual coverage and freshness. Use minute intervals to inspect a young launch and longer intervals for established history. Returns unavailable with no_pool when no pool prices the token; source failures carry their reason and are not zero prices. Needs no feature flag. - [Get a token's holders](/api-reference/solana/get-token-holders.md): Lists a Solana token's ten largest holders, read from the chain: each owner once with all its accounts added up, its share of the supply, whether a program controls it rather than a person (a pool, a vault or a launchpad's bonding curve) and, where Fin recognizes it, whose pool that is, and whether it is the wallet that created the token. The answer also carries how much the number of wallets holding it changed, as a percent per window, where the data source states it. Use it to see how concentrated a token is before a trade; Get a Solana token's `topHoldersPct` is the venue's own summary of the same. Answers `unavailable`, never an error, when the chain cannot be read just now; an address that is not a token is not found. Needs no feature flag. - [Get a token icon](/api-reference/solana/get-token-icon.md): Answers a Solana token's icon as an image: the picture the data source lists for it, fetched by Fin rather than by the person's browser, and served only as a PNG, JPEG, WebP or GIF, with the type its own bytes show. Use the `iconUrl` a token read gives, and draw a placeholder when it answers not found: the data source lists no icon, or its icon is unreachable, too large or another kind of file. It needs no feature flag. - [List suggestions](/api-reference/suggestions/list.md): Returns what Fin suggests for one page of your app, best first: moves on the user's own orders, automations and money, each with the exact terms its review draws. Fin reads the whole account in the background whenever it changes, so this answers at once and never waits on the model: `thinking` means Fin is reading an account it has nothing saved for yet, so read again in a few seconds; `updating` means a newer read is under way while these still hold. Send `timeZone`, `country` and `perpsAllowed` with every read; they apply to this read only. When `status` is `failed` and `retryable` is false, the user's AI spending limit or the hourly limit stopped Fin from looking: say so, and offer no Try again. - [Get a suggestion's review](/api-reference/suggestions/review.md): Checks one suggestion again against the account as it is now and returns it with fresh review terms. Call it when the user opens a suggestion's review, then draw the review from `review` and confirm the move through the routes that make it. When the suggestion no longer holds (the account or the price moved, the user set it aside, or it cannot be made where the user is now), it answers `409 suggestion_changed`: say it changed since Fin suggested it, and read the page's suggestions again. - [Dismiss a suggestion](/api-reference/suggestions/dismiss.md): Sets a suggestion aside when the user picks Not now: Fin stops suggesting that kind of move on that order, automation or asset until it changes or seven days pass, and its next reads leave it out. Safe to repeat. - [List baskets](/api-reference/baskets/list.md): Lists the user's idea baskets, newest first, with estimated values and allocation. Pass nextCursor unchanged to read the next page. Available only to enabled partners. - [Get a basket](/api-reference/baskets/get.md): Returns an idea basket with its bought quantities, estimated values, failed buying steps and unused venue money. Use it to show the idea's details after listing baskets. Holdings are shared with the rest of the account, not reserved for this basket. - [Delete a basket](/api-reference/baskets/delete.md): Removes an idea basket from the user's ideas, for a draft or a basket already bought. It moves nothing: anything the basket bought stays in the user's accounts, and money left on a venue stays there to withdraw. Refused while the basket is buying (`basket_buying`) or while an approval to buy it is open (`basket_awaiting_approval`). Its history stays in the conversation. Not gated by the baskets feature, so a user can always remove their own basket. - [Link an order to a basket step](/api-reference/baskets/link.md): Links an order the user placed to a step of a partly bought basket that did not buy, so the basket shows and values that order in the step's place. Use it after the user bought what a failed step would have bought with an order of their own: pick one of the step's `failures[].linkable` orders from Get a basket. It moves nothing and asks for no approval. A link is permanent; repeating the same link answers the basket again. Once every step that did not buy is linked, the basket is `bought`. Refused when the step bought or the basket is not partly bought (`basket_step_not_failed`), when another order is linked to the step (`basket_step_linked`), or when the order is not one the step can take (`basket_order_not_linkable`). - [Create a user](/api-reference/users/create.md): Creates a user for your app, identified by your own `userId`, together with their agent and their main conversation. Safe to repeat: the same `userId` returns the same user. Call it before the user's first session. It creates no wallet; the user creates that later with a signature (Create the agent wallet). - [Get the signed-in user](/api-reference/users/me.md): Returns the user the session token belongs to and when the session expires. Use it to check that a session is still valid. - [Start wallet sign-in](/api-reference/users/session-challenge.md): Step 1 of wallet sign-in, for apps without their own login. If your app already signed the user in, skip this and call Create a session with the wallet they used. Returns a `message` for the user to sign with their wallet or passkey. Have them sign it exactly as returned, then send `challengeId` and the signature to Create a session within 5 minutes. `origin` must be one of your registered app origins. Signing only proves who the user is; it cannot move funds. The first wallet a user signs in with becomes the one that must sign their wallet creation, withdrawals and approvals. - [Create a session](/api-reference/users/create-session.md): Signs a user in and returns a session token for their requests. If your app has its own login, send `controller`: the wallet or passkey your login verified. Otherwise send the `challengeId` and `signature` from Start wallet sign-in. Send the returned `token` as `Authorization: Bearer …` with your API key on the user's requests. Sessions last an hour and cannot be refreshed; create a new one when it expires. The user's first session registers their wallet for good, and later sessions must name the same one. When the user just created a passkey in your app, also send `createWallet: true`: a session that answers `createsWallet: true` creates their agent wallet with an empty body to Create the agent wallet, so they confirm only the passkey's creation. - [Revoke a session](/api-reference/users/revoke-session.md): Signs the session out: its token stops working at once, including on open event streams. Call it when the user logs out of your app. Runs already started keep going and nothing is deleted. - [List a user's features](/api-reference/users/list-features.md): Lists the features an operator turns on or off for each user, and whether this user has each one now. Use it to show only what the user can use: while a feature is off, the user cannot start it, so its routes refuse and their runs go without it. What the user already has stays readable, and selling, withdrawing and stopping never depend on a feature. Read it again when the user comes back, because an operator can change it at any time. - [Get the main conversation](/api-reference/conversations/main.md): Returns the user's main conversation: the default chat thread every user has, created with the user. Send messages here in a single-chat app. It stays the main conversation when the user creates others. Deleting it gives the user a new, empty main conversation, so read this again rather than keeping its id forever. - [Create a conversation](/api-reference/conversations/create.md): Creates a new conversation for the user, optionally with a title. Most apps use the main conversation (Get the main conversation) and create more only for separate topics. Send an `Idempotency-Key` header to make a retry safe: the same key returns the same conversation. - [List conversations](/api-reference/conversations/list.md): Lists the user's conversations, newest first. By default only chats the user started; `origin=automation` or `all` adds conversations automations started. `order=recent` sorts by latest activity, and `activity=active` keeps only those with a run in progress or an approval waiting. - [Get a conversation](/api-reference/conversations/get.md): Returns one conversation with a summary of its latest activity: last messages, run status and waiting approvals. - [Delete a conversation](/api-reference/conversations/delete.md): Removes a conversation from the user's list. Its history stays readable by id, with `deletedAt` set, but it takes no new messages. Deleting the main conversation gives the user a new, empty one; read Get the main conversation again for its id. Stop a run first: a conversation with a run in progress or an approval waiting is refused. Safe to repeat. - [List a conversation's events](/api-reference/events/list.md): Returns a conversation's saved events, oldest first: messages, runs, approvals and trade updates. Use it to load history or catch up after being offline; pass `nextCursor` back as `cursor` to continue. For live updates use Stream a conversation's events. - [Stream a conversation's events](/api-reference/events/stream.md): Opens a server-sent events stream for one conversation. It first replays saved events after `cursor` (`0` for all of them), then sends new events as they happen, including the agent's reply as it is written. After a disconnect, reconnect with the last event id in `Last-Event-ID` or `?cursor=`. Live text (`agent.text_delta`) is not saved: replace it with the final message when `agent.entry` arrives. - [Start a run](/api-reference/runs/start.md): Sends the user's message to the agent in a conversation and starts it working. Answers `202` with the run at once; the agent works in the background. Follow it on the conversation's event stream, or poll Get a run until `status` is `completed`, `failed` or `aborted`. If the agent needs the user's approval for an action, the run pauses (`paused`) until you approve or deny it. Send an `Idempotency-Key` header to make a retry safe: the same key returns the same run instead of starting another. - [List runs](/api-reference/runs/list.md): Lists the user's runs, newest first. Filter by `conversationId` for one conversation's runs. Each run carries the user's `feedback` on its reply, so one call shows a thread's feedback. - [Get a run](/api-reference/runs/get.md): Returns a run's status, reply, pending approvals, and pending questions, and the user's `feedback` on the reply once they have sent it. A run keeps its id while it pauses for input or approval and resumes. - [Steer a run](/api-reference/runs/steer.md): Sends the user's new message to a run that is still working, so the agent reads it at its next step instead of after the run ends. Use it for a correction or an addition while the agent works; once a run has ended, send the next message with Start a run. Answers `202` with the run: the message is in `steers` as `pending`, and the `run.steered` event marks where the agent read it. If the run is waiting on an approval or a questionnaire, the message declines or skips it and the run continues with the message; it never approves anything. A run that ended or is finishing answers `409 run_not_active` and the message is dropped: send it with Start a run instead. Send an `Idempotency-Key` header to make a retry safe. - [Cancel a run](/api-reference/runs/cancel.md): Stops a run that is in progress or paused, and returns it once it has stopped. Its status is then `aborted`, or the status it reached first if it finished at the same moment. A run that has already ended cannot be cancelled and answers `409 run_not_active`. - [Send run feedback](/api-reference/runs/send-feedback.md): Sends the user's feedback on a run's reply: `up` for a thumbs-up, or `down` for a thumbs-down with an optional `reason` from a fixed list. Call it when the user taps a thumb, once the run has ended (`completed`, `failed` or `aborted`); a run still working or waiting answers `409 run_active`. Sending again replaces the earlier feedback, so it is also how the user changes it, and a retry is safe. Answers the feedback, which Get a run returns as `feedback` from then on; Delete run feedback removes it. A `reason` goes with `down` only: with `up` the request is refused with `400 invalid_input`. - [Delete run feedback](/api-reference/runs/delete-feedback.md): Deletes the user's feedback on a run's reply, so `feedback` on Get a run is `null` again. Call it when the user taps the thumb they already chose. Safe to repeat: a run with no feedback answers the same way. - [Get voice input](/api-reference/voice/get.md): Says whether the user can talk to their agent instead of typing, and the limits a recording keeps to: its longest length, its largest size and the audio types it may be. Use it before showing a microphone: show one only while `status` is `available`, record at most `maxSeconds`, then send the recording to Transcribe a recording. - [Transcribe a recording](/api-reference/voice/transcribe.md): Turns one recording of the user speaking, up to 60 seconds, into text, on the deployment's own model provider. Send the audio's bytes as the body, typed by `Content-Type` with one of the formats Get voice input lists and no larger than that format's `maxBytes` (a larger one answers `413`). Fin waits up to a minute for the speech model, so give the call 75 seconds before giving up: one abandoned sooner is still charged. Put the `text` it answers where the user writes, for them to read, change and send with Start a run or Steer a run: nothing reaches the agent until they do. An empty `text` means no speech was heard. Each transcription is charged to the user's AI usage budget and counted against their hourly and daily transcription limits; Fin keeps neither the audio nor the text. - [Get a question](/api-reference/questions/get.md): Gets a questionnaire the agent is waiting for. Use this route to restore the questions and their current status after reconnecting; submit an answer with Answer a question. - [Answer a question](/api-reference/questions/answer.md): Submits the user's answers to a questionnaire, leaving out any question they skipped, or skips it whole. Use this route when a run is waiting for user input; it returns the questionnaire after the answer is accepted. Send the same `Idempotency-Key` and body again to safely retry; a changed body under the same key is refused with `request_key_conflict`. - [List approvals](/api-reference/approvals/list.md): Lists the user's approvals, newest first. By default only those waiting for a decision; pass `status` for decided or expired ones, or `all`, and `conversationId` for the approvals asked for in one conversation. - [Get an approval](/api-reference/approvals/get.md): Returns an action the agent wants to take that needs the user's OK, with the exact amounts, assets and limits to show them before they decide. For a money action it also carries `authorization.message`: the text the user signs with their wallet to approve it. - [Approve an action](/api-reference/approvals/approve.md): Records the user's approval and resumes the paused run, which then carries out the action. Returns the approval. For a money action, send `authorization` with the user's signature of `authorization.message` from Get an approval. Approving does not mean the action succeeded: follow the run, or the trade (Get a trade), for the result. - [Deny an action](/api-reference/approvals/deny.md): Records the user's refusal and resumes the paused run, which carries on without the action. Returns the approval. - [Get the agent wallet](/api-reference/wallets/get.md): Returns the user's agent wallet: the wallet the agent deposits to, trades from and withdraws from. Until the user creates it, `wallet` is `null` and `creation` carries the message they sign to create it. If an existing wallet needs its owner's confirmation, `confirmation` carries the exact message to sign for Confirm wallet ownership; it grants no spending permission. - [Create the agent wallet](/api-reference/wallets/create.md): Creates the user's agent wallet. The user signs `creation.message` from Get the agent wallet with their registered wallet; send the signature in `authorization`. If the user signed in with an account-opening message (Start wallet sign-in with `createWallet`, answered `createsWallet: true`), send that sign-in's `challengeId` and `signature` in `signIn` instead, within its five minutes, and the user signs nothing more. If your app's own login opened the session for a passkey the user just created (Create a session with `createWallet`, answered `createsWallet: true`), send an empty body from that session within 270 seconds of opening it. Safe to repeat: an existing wallet is returned as it is. Needed before any deposit; chat works without it. - [Confirm wallet ownership](/api-reference/wallets/confirm.md): Confirms the user's ownership of their existing agent wallet. Use it when Get the agent wallet returns a confirmation message: show the existing account, have the user sign that exact message, and send the signature here. Returns the same wallet with its signed ownership receipt. Safe to repeat; this creates no wallet, moves no funds and grants no spending permission. - [Get wallet account](/api-reference/wallets/get-account.md): Returns the user's agent wallet, whatever its kind, named by `intentsAccount`: its NEAR Intents account and whether that is the wallet's own NEAR account (`near`) or an Agent API wallet's EVM account (`evm`). Use it instead of Get the agent wallet once your partner is enabled for Agent API wallets, or to read `intentsAccount` the same way for every wallet; Get the agent wallet refuses an Agent API wallet with `wallet_account_unsupported`. Until the user has a wallet, `creation` carries the message they sign for Start wallet setup; for an Agent API wallet, `renewal` carries the message they sign for Renew wallet access. - [Get wallet account balances](/api-reference/wallets/get-account-balances.md): Returns what the agent wallet holds, exactly as Get balances does, with the wallet named by `intentsAccount` whatever its kind. Use it instead of Get balances once your partner is enabled for Agent API wallets, which Get balances refuses with `wallet_account_unsupported`. - [Open a wallet account session](/api-reference/wallets/open-account-session.md): Creates a 1Click session for the agent wallet, exactly as Get a 1Click session does, naming the account it signs in as by `intentsAccount` whatever the wallet's kind. Use it instead of Get a 1Click session once your partner is enabled for Agent API wallets, which that route refuses with `wallet_account_unsupported`. Keep both tokens on your server, refresh the access token with 1Click, and call this again after `refreshTokenExpiresAt`. Every call is a separate session that cannot be revoked. - [Start wallet setup](/api-reference/wallets/start-setup.md): Sets up the user's agent wallet with the same consent Create the agent wallet takes (`authorization` over `creation.message`, `signIn`, or an empty body from the session that opened the account with a new passkey). Use it instead of Create the agent wallet when your app can show the user a wallet setup step: where your partner is enabled for Agent API wallets, the wallet is an agent the user owns in the NEAR Intents Agent API, and the answer is `signature_required` with the first `step` to sign; send the signature to Continue wallet setup. Otherwise it creates the wallet exactly as Create the agent wallet does and answers `completed`. For an existing Agent API wallet, send an empty body: if its policy needs limit orders enabled, the answer is a `policy_update` step for the user to sign; all other policy settings stay unchanged. The wallet it answers is named by `intentsAccount`: read it afterwards with Get wallet account. Safe to repeat: a setup under way answers its current step, and an up-to-date wallet answers `completed`. - [Continue wallet setup](/api-reference/wallets/continue-setup.md): Sends the user's signature of a wallet setup step from Start wallet setup, Renew wallet access or a previous call: have their wallet or passkey sign `step.intent.payload` unchanged as `step.intent.standard` says, then send `step.setupId` and the intent with their wallet's output added. Answers the next step to sign, or `completed` with the wallet. A step past its `expiresAt` answers a fresh step to sign instead. If the call times out, send it again unchanged; `provider_unavailable` means the step is still landing, so try again in a few seconds. - [Renew wallet access](/api-reference/wallets/renew-access.md): Renews the agent's access to the user's Agent API wallet, which lasts a year from setup. Use it when Get wallet account answers a `renewal` message and the access is close to running out, or the agent can no longer act: the user signs `renewal.message`, send it here, then have them sign the answered step and send it to Continue wallet setup. The wallet and its funds stay as they are; nothing moves. - [Add a withdrawal destination](/api-reference/wallets/add-destination.md): Lets the user's Agent API wallet pay one more address, which only the user's own signature can allow: a withdrawal, a send or a venue account's funding to it. Name the address by `network` and `address`, or name a `venue` (`perps`, `prediction`, `solana`) to allow the agent's own account there that funding the venue pays: Fin names its exact address and chain, opening the account first when it is new. The answer is `signature_required` with the step they sign (`step.intent`, shown with `step.summary`); send their signature to Continue wallet setup, which answers `completed` once the address is allowed. An address already allowed answers `completed` at once. Use it when a transfer from an Agent API wallet is refused with `destination_not_allowed` (a venue funding's refusal names its venue), or before the user's first funding of a venue; from setup the wallet may pay only the user's own sign-in wallet and their own NEAR Intents account. A venue the user cannot trade is refused with its own reason (`perps_disabled`, `prediction_disabled`, `solana_disabled`), and a Polymarket account still opening with `no_account`: ask again within a minute. A wallet can change what it allows once every few minutes: sooner, this refuses with `policy_change_throttled` and `Retry-After`, and nothing is asked or signed. - [Get a 1Click session](/api-reference/wallets/create-session.md): Creates a 1Click session for the agent wallet, so your backend can read its balances, history and orders from 1Click with the code you already use for your own users. Call it when you hold no usable refresh token for the agent: after the user signs in, or once 1Click refuses the refresh token. Keep both tokens the way you keep your own 1Click tokens, on your server or in HttpOnly cookies, refresh the access token with 1Click, and call this again after `refreshTokenExpiresAt`. Every call is a separate session that cannot be revoked, so delete yours when the user signs out. - [Get balances](/api-reference/wallets/balances.md): Returns what the agent wallet holds: each asset with its amount, price and USD value, and the available-wallet total, read from the provider on every call. Use `portfolio` for separately qualified wallet and order figures: its combined total is null when allocation or settlement evidence cannot prevent counting funds twice. Show the available balance while that total is unknown. When a deposit limit applies, `depositLimit` says how much more the user can deposit right now. - [Get a withdrawal quote](/api-reference/wallets/quote-withdrawal.md): Step 1 of a withdrawal. Prices a withdrawal from the agent wallet and returns the exact `terms` (amount, fees and the minimum the recipient will receive), `authorization.message` for the user to sign, and the `requestKey` to send as the `Idempotency-Key`. Nothing is reserved or sent. Call Withdraw funds before `authorization.expiresAt`. - [Withdraw funds](/api-reference/wallets/withdraw.md): Step 2 of a withdrawal. Sends funds from the agent wallet to an external address or a NEAR Intents account. Send the quote's `terms`, the user's signature of its `authorization.message`, and its `requestKey` as the `Idempotency-Key` header. Returns the withdrawal; poll Get a withdrawal until its `status` is final. If this call times out, send it again unchanged: you get the same withdrawal back, never a second payout. - [List withdrawals](/api-reference/wallets/list-withdrawals.md): Lists the user's withdrawals, newest first, with their status. After a timed-out request, find its withdrawal by filtering on `requestKey`. - [Get a withdrawal](/api-reference/wallets/get-withdrawal.md): Returns a withdrawal and its `status`: `pending` until it starts, `processing` while it is sent, then `completed`, `refunded` (the funds came back to the agent wallet) or `failed` (nothing left the wallet; `failureReason` says why). `denied` and `expired` mean the request was refused or its signature ran out before it started. `uncertain` means the result could not be confirmed yet: never send a replacement, keep checking. - [List supported assets](/api-reference/wallets/supported-assets.md): Lists the assets and networks the agent wallet can deposit and withdraw, with the ids to use in deposit and withdrawal requests. A listed asset can still be unavailable for a particular amount; the quote tells you. - [Get a deposit quote](/api-reference/wallets/quote-deposit.md): Prices a deposit of an exact amount before it is created: what the agent wallet would be credited now, and the least it will be credited within the loss limit. Use it while the user chooses an amount. Nothing is reserved and no address is issued. Then call Create a deposit with the same amount and `terms.minimumCreditRaw` set to `minimumCreditRaw`; it prices the deposit again when it issues the address. `provider_unavailable` also means 1Click cannot price it within the loss limit right now. - [Create a deposit](/api-reference/wallets/create-deposit.md): Creates a deposit of an exact amount into the agent wallet and returns where to send it. The user sends that amount from their own wallet before `sendBefore`. Each address belongs to this deposit only; never reuse it. Poll Get a deposit to see it credited. When the amount isn't known yet, such as a withdrawal from an exchange, use Create a deposit address instead. When a deposit limit applies, a deposit that would take the agent wallet past it is refused with `deposit_limit_exceeded` and nothing is recorded: Get balances says how much fits in `depositLimit.availableCents`. Requires an `Idempotency-Key` header: the same key returns the same deposit. - [List deposits](/api-reference/wallets/list-deposits.md): Lists the user's deposits, newest first. After a timed-out request, find its deposit by filtering on `requestKey` (the `Idempotency-Key` you sent). - [Get a deposit](/api-reference/wallets/get-deposit.md): Returns a deposit and its status: waiting for funds, credited or refunded. Each read checks the provider for news. - [Create a deposit address](/api-reference/wallets/create-deposit-address.md): Creates a one-time address that takes one transfer of any amount into the agent wallet. Use it instead of Create a deposit when the amount isn't known yet, such as a withdrawal from an exchange: name the asset and the network the user sends on, and nothing else, since whatever can't be credited, such as a transfer below `instruction.minimumDepositRaw`, is refunded to the agent wallet itself. Show `instruction.address` (with `memo` when set), then poll Get a deposit address to see the transfer credited; Report a deposit transaction finds it sooner. When a deposit limit applies, the address is refused with `deposit_limit_exceeded` once the wallet has no room left, and nothing is recorded. When 1Click won't make an address for the asset on that network, such as a network it doesn't quote right now, it is refused with `quote_refused` and no address is issued: offer another network. Nothing caps what the user sends to an address, so tell them how much fits from Get balances' `depositLimit.availableCents`. Requires an `Idempotency-Key` header: the same key returns the same address. - [Get a deposit address](/api-reference/wallets/get-deposit-address.md): Returns a deposit address and how its transfer is going: waiting for it, below the minimum, credited or refunded to the agent wallet. Each read checks the provider for news, so poll it while the address is on screen. - [Report a deposit transaction](/api-reference/wallets/report-deposit-transaction.md): Tells Fin the transaction that paid a deposit address, as the user's wallet or exchange shows it, so the transfer is found sooner than by watching the address alone. It is optional: the address is watched either way. Returns the deposit address as it stands after the report. A hash that isn't a transfer to this address is refused with `invalid_input`. Safe to repeat. - [List earn vaults](/api-reference/wallets/list-earn-vaults.md): Lists the curated yield vaults (near.com's Earn vaults) the agent wallet can deposit into, each with the yearly rate its provider states now, its total value locked, its payment asset and the user's own position in it. Use it to show a vault's current rate beside a deposit or a scheduled harvest, and what a position has earned; a deposit is a swap from the vault's payment asset into its `assetId`, and a withdrawal the swap back. A rate is the provider's variable figure, read at most every five minutes, never a promise: `rate` is null when the provider could not be read just now, so show no figure rather than an old one. A position states what its trades paid and returned in the payment asset, never a price: work out what it earned as what its shares are worth in that asset now, plus `withdrawnRaw`, less `depositedRaw`, and only while its `costBasisStatus` is `complete`. - [Get a swap quote](/api-reference/wallets/quote-swap.md): Step 1 of a swap. Prices swapping one asset the agent wallet holds for another and returns the exact `terms` (what it sells, what it buys and the least it receives), `authorization.message` for the user to sign, and the `requestKey` to send as the `Idempotency-Key`. Use it for a swap the user makes from your own screen; the agent proposes its own trades in chat. Nothing is reserved or swapped. Call Swap tokens before `authorization.expiresAt`. - [Swap tokens](/api-reference/wallets/swap.md): Step 2 of a swap. Swaps one asset in the agent wallet for another within the quote's terms; what it buys stays in the agent wallet. Send the quote's `terms`, the user's signature of its `authorization.message`, and its `requestKey` as the `Idempotency-Key` header. Returns the swap; poll Get a swap until its `status` is final. If this call times out, send it again unchanged: you get the same swap back, never a second one. - [List swaps](/api-reference/wallets/list-swaps.md): Lists the swaps the user made with Swap tokens, newest first, with their status. The agent's own trades are in List trades. After a timed-out request, find its swap by filtering on `requestKey`. - [Get a swap](/api-reference/wallets/get-swap.md): Returns a swap and its `status`: `pending` until it starts, `processing` while it runs, then `completed` (the bought asset is in the agent wallet), `refunded` (the sold asset came back) or `failed` (nothing was swapped; `failureReason` says why). `denied` and `expired` mean the request was refused or its signature ran out before it started. `uncertain` means the result could not be confirmed yet: never send a replacement, keep checking. - [Read current remaining actions](/api-reference/wallets/get-remaining-trade-actions.md): Reads current proof-backed recovery candidates after settlement observations change. Indices are local frozen-leg positions. A recovery child's existing original-action map identifies its root. This read reserves nothing, creates no review and moves no funds; fresh proposal preparation rechecks all proof under lock. - [Review remaining actions](/api-reference/wallets/prepare-remaining-trade.md): Prepares a fresh review of unfinished actions in this root trade's original conversation. A fresh Idempotency-Key permits a new business attempt only after conclusive refund or non-execution proof; an already settled or uncertain action is never repeated. Selection includes unfinished prerequisites and descendants while independent successful branches stay excluded. Show every returned action and obtain its fresh signature. Different terms conflict while a review is active. Exact-input debits and exact-output swap targets stay fixed; current prices can change receive amounts or input ceilings. Explicit payout minimums stay enforced. The original grant and its spent signatures never change. - [List trades](/api-reference/wallets/list-trades.md): Lists the trades the agent made or proposed, newest first, each with its `status` and receipts. Filter by `runId` or `conversationId`. - [Get a trade](/api-reference/wallets/get-trade.md): Returns a trade and its `status`: what the agent asked for, who approved it, the plan it ran and the result of each step. A finished run or a granted approval does not mean the trade settled; its `status` does. While it is `pending`, `processing` or `uncertain` it can still change: check again, and never ask the agent for a replacement. - [Prepare an order](/api-reference/wallets/prepare-order.md): Step 1 of placing a limit order. Checks the order against the agent wallet and returns its exact `terms`: what it sells, what it buys, the least it sells at, how long it rests, and `minimumReceivedRaw`, the least the whole order receives at its limit price. Also returns `authorization.message` for the user to sign and the `requestKey` to send as the `Idempotency-Key`. Use it for an order the user places from your own screen; the agent proposes its own orders in chat. Nothing is reserved or placed. Call Place an order before `authorization.expiresAt`. - [Place an order](/api-reference/wallets/place-order.md): Step 2 of placing a limit order. Places the prepared order in the agent wallet, funded with the amount it sells: it rests until it fills at the limit price or better, expires or is cancelled, and what it buys comes back to the agent wallet. Send the prepared `terms`, the user's signature of its `authorization.message`, and its `requestKey` as the `Idempotency-Key` header. Returns the order: `funded` once it rests, or `abandoned` with a `failureReason` when nothing was placed. Follow its fills with Get a limit order. If this call times out, send it again unchanged: you get the same order back, never a second one. - [List limit orders](/api-reference/wallets/list-orders.md): Lists the user's limit orders, newest first: the approved terms, whether the order is funded, how much has filled, and any cancellation. After a timed-out Place an order, find its order by filtering on `requestKey`. - [Get a limit order](/api-reference/wallets/get-order.md): Returns a limit order and its current state. `unconfirmed` means the provider's answer was lost; never place a replacement, keep checking. - [Cancel a limit order](/api-reference/wallets/cancel-order.md): Asks 1Click to cancel one of the user's limit orders, for a cancel button on your own orders screen; the agent cancels through an approval in chat instead. Returns the order with `cancelRequestedAt` set: what filled stays filled, and cancellation can race a final fill. Read the order for its terminal fill status and `position`: canceled or expired input stops resting, while refund principal and provider payout completion remain separate from net wallet reconciliation. Asking again is safe, and answers the order as it stands. - [List grids](/api-reference/wallets/list-grids.md): Lists the user's grids, newest first: each grid's state, the terms the user approved, every cell's current order, completed buy-then-sell cycles and realized profit. A grid starts when the user approves one in chat; follow a single grid with Get a grid. - [Get a grid](/api-reference/wallets/get-grid.md): Returns one grid as it stands: its state, approved terms, cells with their current orders, cycles, realized profit and the base it holds. Each cell order's `id` reads with Get a limit order for its fills and payouts. - [Pause a grid](/api-reference/wallets/pause-grid.md): Stops a running grid placing orders and cancels the orders its cells rest, keeping its approval and each cell's side, so Resume a grid can start it again. Only an `active` grid can be paused. Cancellation is asynchronous: a last order may still fill, and the grid's cells show each order until it ends. - [Resume a grid](/api-reference/wallets/resume-grid.md): Starts a paused grid again under the approval it already has: each cell places its order again on the side it was on, until the grid's original end. Only a `paused` grid with at least an hour left can be resumed, and only while grid trading is on for the user. - [Cancel a grid](/api-reference/wallets/cancel-grid.md): Stops a grid for good: cancels every order its cells rest and withdraws its approval. Nothing is sold; what it bought stays in the agent wallet. The grid answers `stopping` until its last order ends, then `stopped`. Cancelling a grid the user already cancelled answers it as it stands, so asking again is safe. A changed grid is a new approval in chat. - [Get portfolio](/api-reference/portfolio/get.md): Returns what the agent owns across every account right now: the total, each account, and each holding with its amount, price and how it was found, value, 24-hour change and average cost. Use it for any figure you show; use Get balances for the amounts a deposit or withdrawal can use. A holding no market prices is left out of the total and listed in `excluded`, never counted as zero. Figures after an account's last check against its custodian are `provisional`: show the value, and say it is unconfirmed. Opening it also asks for fresh reads of accounts last read more than two minutes ago, so calling it again shortly may confirm them. - [Get portfolio history](/api-reference/portfolio/history.md): Returns the value of everything the agent owns over a range, one point per step, with the gain and a summary of the money that came in and went out. Use it to draw the portfolio chart; its last point is always Get portfolio's total. `marks` say where a holding entered or left the valued set, or where a change no record explains landed; neither counts as gain. Pass `step` for coarser points, such as `1d` over `1M`; a step finer than the range is kept at is refused. - [List activity](/api-reference/activity/list.md): Lists what happened in the user's wallet and automations, newest first: the agent's trades, its Solana trades and transfers, the user's own swaps, withdrawals, deposits, transfers to deposit addresses and changes to automations. Each item carries the same object its own route returns, so render it by `kind`. Narrow it with `type` and `origin`, and pass `nextCursor` back as `cursor` for older items. A deposit or deposit address appears once the user is expected to send to it; one that expired unpaid is only in List deposits or Get a deposit address. - [List notifications](/api-reference/notifications/list.md): Lists what Fin told the user, newest first, with each notification's text ready to show: approvals and questions waiting for them, automation reports, money that moved, problems with their automations and fin's replies in chats they left. Show it as an inbox, use `unreadCount` for a badge, and open each notification's `subject` when the user taps it. Narrow it with `unread` or `conversationId`, and pass `nextCursor` back as `cursor` for older ones. Mark notifications read once the user has seen them. - [Mark notifications read](/api-reference/notifications/mark-read.md): Marks the user's notifications read once they have seen them, on every device: name them in `notificationIds`, or send `through` with the newest one the user saw to mark it and everything older, so one that arrived since stays unread. Answers the newest 100 notifications this call changed and the new `unreadCount`; a `through` request still marks every older notification, so refresh the inbox for the rest. Safe to repeat: a notification already read is left as it was. An approval or a question counts as read on its own once it is answered or runs out. - [Get AI usage budget](/api-reference/budgets/get.md): Returns the user's AI usage budget for today and this month: the limit, what is spent, what running work has reserved, and what is left. When nothing is left, new runs are refused with `budget_exhausted` until the next day or month. This is the cost of running the agent, not the money in the user's wallet. - [Get partner usage](/api-reference/partner/usage.md): Exports attributed run model invocations and exact known costs, reserved maximums and uncertain exposure for an original UTC budget period. Totals include your users' runs, the partner's own runs, suggestions and voice transcriptions; suggestionTotals and voiceTotals identify the portions without a run, and partnerRunTotals the portion of runs Fin makes for the partner itself (market briefs), which the page leaves out. Page rows and totals share one database snapshot. Contains no prompts, credentials, trading balances or customer billing. - [Get partner quotas](/api-reference/partner/quotas.md): Returns configured request, run, stream and inference limits shared by every key and user of this partner, with current utilization and effective budget-period caps, including any operator adjustments. Use periods[].capCents for the current period's allowance; limits contains the configuration for future periods. Reading this snapshot does not reserve capacity. - [List partner features](/api-reference/partner/features.md): Lists the features an operator turns on or off for your key rather than for each user, such as `market_briefs` or `disable_invite_code_requirements`, and whether your key has each one now. Use it for what your app offers before anyone signs in; for what one signed-in user can use, call List a user's features. Read it each time you need the answer, because an operator can change it at any time. - [List notifications to deliver](/api-reference/partner/notifications.md): Lists every notification of your users, oldest first, for you to deliver to their devices: each one names its user by your own `userId` for them and says with `push` whether to show it now. Poll it from your server every few seconds with your partner key alone, keep the `nextCursor` it answers, even from an empty page, and pass it back as `after`, including after a restart. A notification takes its place here once it is committed and its short wait has passed, so a cursor never skips one. Approvals, questions and replies wait a little first, in case the user sees them in the app. - [List market subjects](/api-reference/market/subjects-list.md): Lists what a market brief can be about: the market, chains, assets, an asset's copy on one chain, and stocks, each with the identifiers that also name it. Pass `alias` to find the subjects a CoinGecko id, symbol, contract address or 1Click asset id names, and `kind` for one kind. - [Create a market brief](/api-reference/market/briefs-create.md): Starts a brief on what the scope did over the window, with possible explanations and sources. Use `mode: news` to research a quiet price move; the default `auto` mode may answer a quiet scope at once with `status: ready`, free. A researched job answers 202 `generating`; read it with Get a market brief until it is `ready` or `failed`. Research is charged to your partner. Cache by `scope`, `window` and `mode`. - [Get a market brief](/api-reference/market/briefs-get.md): Answers a brief job your partner key created: `generating`, then `ready` with the brief, or `failed` with why. - [List market stories](/api-reference/market/stories-list.md): Lists the stories the crypto market is telling now, most recently confirmed first: each a few sentences on what happened, what it is about, how well it is backed and its newest sources. Use it for a news feed or a home page; pass `evidence: reported` to leave out stories only one unreviewed source tells, and `subject` for one coin, stock or market. Open a story with Get a market story for all its sources, its figures and the moves on what it is about. A page can hold fewer stories than `limit` while `nextCursor` is set: keep paging until it is null. - [Get a market story](/api-reference/market/stories-get.md): Returns one story in full: every article it rests on, newest first, the market figures it states as they read now, and the moves Fin spotted on what it is about since the story began. Use it when a reader opens a story from List market stories. A story Fin no longer shows, because its sources were withdrawn or its figures can no longer be read, answers `404 story_not_found`: drop it from what you show. - [List market headlines](/api-reference/market/headlines-list.md): Lists the latest articles from reviewed newsrooms and official sources, newest first, each with where to read it and the coins and stocks its headline names. Use it for a column of the latest news beside the stories; posts, project announcements and unreviewed sites are left out. Pass `subject` for the articles naming one coin or stock: that reads the newest 300 articles only, so it lists recent coverage, not an archive. - [List market moves](/api-reference/market/moves-list.md): Lists the moves Fin spotted in the market, newest first, each as one plain sentence with its size and window: a coin's price, the whole market, a prediction market's odds or its resolution, a venue's volume, a launchpad's share, a new leader or a newcomer to a top list. Use it for a live ticker of what is moving; narrow it with `kind` or `subject`. Each market has one line per kind and each leaderboard one line of lead changes, a newer move replacing the older one on its line, so poll the first page rather than keeping every move; a page can hold fewer moves than `limit` while `nextCursor` is set. - [Get market flows](/api-reference/market/flows-get.md): Returns where money is in the crypto market: total market cap, alt trading volume, perps open interest, stablecoin supply, DEX volume and launchpad volume, each with its change over a day, a week and a month. Use it as the backdrop beside the stories. A figure Fin does not have right now is left out, so show the rows you get. - [List automation data sources](/api-reference/automations/list-sources.md): Lists what an automation can watch (for example prices or incoming webhooks), the settings each takes, and whether this user can use it. - [List automations](/api-reference/automations/list.md): Lists the user's automations with their status, next run and latest run. `filter=current` hides deleted ones. Automations are created by chatting with the agent; there is no create route. - [Get an automation](/api-reference/automations/get.md): Returns an automation: its name, its instructions, a readable `summary` of when it runs, its status and its latest run. - [Delete an automation](/api-reference/automations/delete.md): Stops an automation for good. Its history stays readable. Safe to repeat. - [Pause an automation](/api-reference/automations/pause.md): Stops the automation until you resume it and cancels runs waiting to start. Runs already going finish, but a run that started before the pause cannot trade. If it may trade on its own (it has a `contract`), it keeps that permission, so resuming needs no new signature. - [Resume an automation](/api-reference/automations/resume.md): Starts a paused automation again, under the trading permission it already has. Refused once that permission has been revoked; the user then sets the automation up again. For one fin paused for its owner, pass `countMissedRun=true` when the owner lets the missed run go, so it counts toward the run limit. - [List an automation's runs](/api-reference/automations/list-runs.md): Lists each time the automation ran or was due to run, newest first, with the outcome and the agent run it started. - [Get an automation run](/api-reference/automations/get-run.md): Returns one time the automation ran: when and why, whether it started or was skipped, and the agent run and approvals involved. - [List automation readings](/api-reference/automations/list-readings.md): Lists what each source the automation reads reported over a window: the source's latest reading, and the values over time of each field the rule compares, so you can draw them against the rule's thresholds. Covers the last 30 days unless you pass `since` and `until`, at most 90 days apart. Each field returns at most 240 points, the last reading of each equal slice of the window. - [Rotate the webhook secret](/api-reference/automations/rotate-webhook-secret.md): Creates a new secret for the automation's webhook and returns it with the webhook's path. The old secret stops working at once. The secret is shown only once. Only for an active automation that runs on incoming events. - [Backtest an automation](/api-reference/automations/backtest.md): Estimates how a draft or saved automation would have behaved over a historical range. Use it before creating or changing an automation; inspect the returned status, limitations and timing changes before using the estimate. Historical prices do not establish executable fills. - [Send an automation event](/api-reference/automations/receive-event.md): Delivers an event from your system to an automation that runs on incoming events. Authenticate with its webhook secret in `X-Automation-Key` (not your API key). Answers `202` when the event is recorded and `200` when you already sent the same event `id`, so resending is safe. Events must be under 5 minutes old and at most 16 KiB.